API Versioning
Versioning API
Il versioning dell'API è un piano per nominare, modificare, supportare e ritirare i contratti API senza rompere i client. Non esiste un URL o uno stile di header che ogni API debba usare.
Un altro esempio
Un'API per buste paga pubblica il contratto OpenAPI `2026-07` e mantiene funzionanti i client `/v1`. Aggiungere un campo opzionale non li rompe. Cambiare `netPay` da centesimi interi a decimale richiede un nuovo contratto principale. Servono anche guide allo spostamento, intestazioni di deprecazione, dati sull'uso e una data di ritiro.
Parti principali
- 01Identificatore del contratto
- 02Regole di compatibilità
- 03Depricazione e migrazione
Usalo quando
Imposta prima le regole di compatibilità, cambia tipi, il metodo di scoperta, il periodo di supporto e la politica di deprecazione. Poi scegli un percorso, un tipo di media o uno stile di intestazione.
Non usarlo quando
Non creare una nuova versione dell'API per ogni rilascio. Non promettere supporto per sempre senza dati di utilizzo e un modo per ritirare le vecchie versioni.
Nome usato nel codice
explicit compatibility policy + versioned OpenAPI document + deprecation and sunset lifecycle Prima di spedire
Check contracts and invariants, authorization, and input limits. Test retries, one-time effects, timeouts, and partial failures. Verify data integrity, compatibility, monitoring, recovery, and rollback.
Outcome: Complete the task with Versioning API (API Versioning). User context: Un'API per buste paga pubblica il contratto OpenAPI `2026-07` e mantiene funzionanti i client `/v1`. Aggiungere un campo opzionale non li rompe. Cambiare `netPay` da centesimi interi a decimale richiede un nuovo contratto principale. Servono anche guide allo spostamento, intestazioni di deprecazione, dati sull'uso e una data di ritiro. Technical concept or control: Versioning API (API Versioning). Why it fits: Imposta prima le regole di compatibilità, cambia tipi, il metodo di scoperta, il periodo di supporto e la politica di deprecazione. Poi scegli un percorso, un tipo di media o uno stile di intestazione. Do not use it when: Non creare una nuova versione dell'API per ogni rilascio. Non promettere supporto per sempre senza dati di utilizzo e un modo per ritirare le vecchie versioni. Engineering requirements: Define inputs, outputs, contracts, and rules that must always hold. Set authorization and input checks. Define failures, timeouts, retries, one-time effects, data moves, and compatibility limits. Operations: Add useful signals and logs that hide sensitive data. Set capacity limits and write an operator guide. Test recovery and rollback. Acceptance criteria: Contract and failure-path tests pass. Data and authorization rules still hold during retries and partial failures. Check performance limits, monitoring, recovery, and rollback. Evidence and limits (evidence boundary): Nessun singolo standard ufficiale controlla l'intero termine. Il suo significato può cambiare tra team, piattaforme o framework. Unknowns to confirm: Where the code runs, data stores, traffic shape, consistency needs, and the security boundary. Also confirm the compatibility period, service goals, and rollback limits.
Controlla questa richiesta
Review how Versioning API (API Versioning) is used now. Definition: Il versioning dell'API è un piano per nominare, modificare, supportare e ritirare i contratti API senza rompere i client. Non esiste un URL o uno stile di header che ogni API debba usare. Release checks: Check contracts and invariants, authorization, and input limits. Test retries, one-time effects, timeouts, and partial failures. Verify data integrity, compatibility, monitoring, recovery, and rollback. Before changing code, list the evidence, gaps, severity, and the smallest safe fix.