Compatibilità API e aggiornamento

1) Principi di base per la compatibilità

Additive-first - Aggiungi uno nuovo senza rompere il vecchio (nuovi campi/endpoint opzionali, nuovi valori enum).
Contratti stabili: «Quello che è stato promesso nelle specifiche funziona»; comportamento documentato.
Backward> Forward: priorità di interoperabilità forward è consentito tramite tolerant-readers.
I documenti sono originali: l'unica fonte di verità è la versione dello schema in registry (OpenAPI/AsyncAPI/Proto).
Una chiara evoluzione: breaking - solo attraverso la nuova versione maggiore e la guida migratoria.

2) Tassonomia delle modifiche

2. 1 Compatibili (MINOR/PATCH)

Aggiunge campi/heder opzionali, nuovi endpoint, parametri query con default.
Aumenta i limiti ('page _ size', TTL), chiarisce gli errori senza cambiare codice/semantica.
Aggiunge valori enum se i client ignorano «estranei» (tolerant-reader).

2. 2 Ambiguo (Behavioral)

Cambiare i default, l'ordine di ordinamento, i minimi timeout e le quote può «rompere» la logica aziendale. Richiede RFC + annuncio e canarini.

2. 3 Rompitori (MAJOR)

Rinomina o rimuove i campi, modifica del tipo/formato, sostituzione dei codici di errore, interoperabilità dei contratti/schemi di autenticazione.

3) Criteri di versioning

Strategia: «path versioning» («/v1 », «/v2»).
Minor/patch, «aggiungi, non rompere».
Le intestazioni datate (dop.) sono «X-API-Variante-Date» per le modifiche progressive lievi.
Tipi di media (opz.) : `Accept: application/vnd. acme. v1 + json'per granulazione sottile.

4) Deprecazioni e sunset

4. 1 Titoli di comunicazione

Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"

4. 2 Ordine di output

1. Annuncio sul portale/distribuzione/SDK release note.
2. La finestra di avviso è di 90-180 giorni.
3. States in dashbord adoption.
4. Dopo sunset: 410 Gone o «read-only» modalità per il periodo grace, se concordato.

5) Migrazioni e coesistenza di versioni

Dual-write/dual-read durante il periodo di transizione e il report.
Adattatori (temporanei) - Le conversioni gateway dei vecchi payload sono nuove. la durata dell'adattatore è limitata.
Assistenza SDK: release che supportano entrambe le versioni con avvisi di deprecazione (1 volta per processo).
Flag Fiech - Abilita una nuova semantica nell'elenco chiavi/tenenti.

6) Backward e compatibilità forward

6. 1 Backward (i vecchi client ↔ un nuovo server)

Non modificare i formati di tipo/obbligatorietà.
I nuovi campi sono solo opzionali.
I nuovi codici aggiungono, non sostituiscono, sono i vecchi «error _ code».

6. 2 Forward (nuovi client ↔ vecchio server)

Controlla la disponibilità (capabilities) tramite OPZIONI//versioni.
Grace-comportamento: il client deve essere tollerato con le fitte mancanti.

7) Contratti e controlli automatici

Archiviare le versioni degli schemi I rapporti «breaking/no-breaking» sono stati resi noti.
Linter: nomi/tipi, idempotenza, paginazione, codici stabili.
CDC (Consumer-Driven Contracts) - Test degli integratori del fornitore CI (Pact e analoghi).
Gate: il PR viene bloccato con breaking senza «major bump »/RFC.

yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml

8) Rilascio canarino e ritorno

Canary: 10% → 25% → 50% → 100% traffico; Ritorno automatico in caso di deterioramento dello SLO (5xx/latency/429).
Chiavi beta - Accesso alle nuove versioni allowlist.
Release freeze - Durante la combustione, errore-budget.
Analisi accettazione: quota di traffico/client sulla nuova versione, tempo di migrazione.

9) Compatibilità nei dettagli: errori, paginazione, idipotenza

9. 1 Errori

Non modificare gli stati HTTP negli script esistenti.
«errore _ code» è stabile; nuovi codici solo da aggiungere.
'Application/perfem + json 'è un unico formato.

9. 2 Paginazione

Passa a cursor/keyset = MINORE se è supportato il vecchio «offset/limit».
Documentare l'ordinamento «(updated _ at, id)» e la stabilità del cursore.

9. 3 Idempotency

Per write, «Idempotency-Key» + «409 IDAMP _ REPLAY» in caso di conflitto.
Le migrazioni non devono cambiare la semantica dell'idempotenza.

10) Gateway-trasformazione (se appropriato)

Map campi, normalizzare gli errori, convertire i formati data/denaro.
Le trasformazioni sono trasparenti e logiche; non nascondere breaking, ma utilizzare come ponte a tempo limitato.

11) Comunicazioni e portale

Changelog с датами (`added/changed/deprecated/removed/fixed`).
La scheda di versione è lo stato (beta/GA/deprecated), la data sunset, i collegamenti alle gate.
Webhoop di notifica: 'deprecation. notice`, `version. released`, `plan. change`.
SDK release note + striscione sul portale.

12) Metriche di successo

Adoption rate v2 (per richiesta/client).
Backward-compat incidents.
Errore mix (quota 4xx/5xx/429) prima/dopo il lancio.
Time-to-Adopt mediana.
Supporto load (tickets/ned).
Cost-to-Serve (costo di infrastruttura per chiamata).

13) Modelli e esempi

13. 1 Intestazioni versioni e deprecazioni

X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"

13. 2 Criteri di versione (frammento YAML)

yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]

13. 3 OpenAPI - Aggiunta di un campo compatibile

yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive

14) Assegno foglio di rilascio (MINOR/MAJOR)

MINOR

• DIFFERENT: no-breaking, linter verde
• Documentazione/SDK aggiornata (esempi/codec)
• Canarino + autotrasporto SLO
• Piano comm, pagina del portale
• Dashboard adoption e errori

MAJOR

• RFC/ADR, data sunset e finestra ≥90 -180 giorni
• Ponte v1↔v2 (gateway) e guida migratoria
• Dual-write/read e compressioni
• SDK con entrambe le API + avvisi
• Pilota con integratori chiave

15) Piano di implementazione (3 iterazioni)

1. Fondamenta (2 settimane):

Registry diagrammi, lente e auto-differf in CI; Criterio di compatibilità titolò Deprecation/Sunset '.

2. Release gestite (3-4 settimane):

Canarie, bandiere Fiech, alert SLO; portale di versione Release SDK con supporto di 2 rami.

3. Automazione e scala (continua):

Test CDC dei consumatori in CI, previsione sunset per le tendenze adoption, notifiche automatiche e avvisi.

16) Mini FAQ

È possibile modificare il tipo di campo senza maggiore?
No, no. Anche «stroka→chislo» - breaking. Inserisci un nuovo campo, vecchio - deprecato.

Enum - È possibile aggiungere valori?
Sì, se i clienti sono tolerant-readers. Altrimenti, prima avvisi e beta.

Quanto devo tenere la vecchia versione?
Per ora, l'adoption del nuovo ≥95% e la finestra di deprecazione. Fissare la scadenza della politica.

Totale

La compatibilità API è una disciplina: approccio additive, schemi formali e difami, release canarie, deprecazioni chiare e migrazioni gestite. Fissare la politica di cambiamento, automatizzare i controlli e le comunicazioni, misurare l'adoption, e i vostri aggiornamenti smetteranno di compromettere i clienti e la velocità di evoluzione aumenterà senza perdere l'affidabilità.