coder / coder/internal

Programmatically catch breaking API changes

Open
#156 1 comment 1 reaction 0 assignees View on GitHub
tech-debt
Dominant language
No language data
Stars
3
Forks
0
PR merge metrics
No merged PRs in 30d

Description

Breaking changes to the API, such as a new status code or differed type, go undetected by our tests. The API is validated by the `codersdk.Client` which is updated alongside the server. So no warnings are raised when api breaking changes occur.

This blind spot leads to us expecting engineers to manually catch breaking API changes in the PR review process.

We should identify these programmatically _without_ adding a chunk of cross-version tests, leveraging something like [`swagger-diff`](https://swagger.io/blog/api-development/using-swagger-to-detect-breaking-api-changes/).

This recently caused a minor regression in [v2.14.0](https://github.com/coder/coder/releases/tag/v2.14.1), where a status code change slipped into our release.

This tool should catch:
- Success status code changes for existing apis: `// @Success 200`
- Removed routes: `// @Router`
- Removed params: `// @Param`
- Type differences on params and success **if fields are removed** (json adding fields is ok)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.