coder / coder/internal

Programmatically catch breaking API changes

Aperta
#156 1 commento 1 reazione 0 assegnatari Vedi su GitHub
tech-debt
Lingua principale
Nessun dato sulla lingua
Stelle
3
Fork
0
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Descrizione

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)

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Direzione di ricerca

Inizia esaminando come vengono mantenuti insieme codersdk.Client e le definizioni dell’API del server, quindi valuta swagger-diff o uno strumento simile di confronto OpenAPI. Usa gli esempi elencati come criteri di accettazione: rileva le modifiche ai codici di stato di successo, le route o i parametri rimossi e le modifiche incompatibili dei tipi, consentendo al contempo l’aggiunta di campi JSON. Conferma che lo strumento rilevi la regressione dei codici di stato di v2.14.0.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
openapi
Ambito
api, backend-api-design
Tipo di issue
Funzionalità
Difficoltà
4/5
Tempo stimato
3-5 giorni
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.