Strategie di versioning API

A cosa serve la versioning

L'API cambia più velocemente dei clienti. La versioning consente di rilasciare feci e modificare errori senza interruzioni delle integrazioni, definisce il rituale di cambiamento e rende l'evoluzione prevedibile. Chiave: modifiche additive predefinite, major solo per l'astinenza, controlli automatici di compatibilità e criteri sunset elaborati.

Principi di base

1. Additive-first: nuovi campi/metodi/eventi opzionali - ok; Eliminare e cambiare il significato è maggiore.
2. MGC (contratto minimo di garanzia) è stabile; arricchimento - attraverso capabilities/'? include = '.
3. Tolerant reader - I clienti ignorano campi sconosciuti e sperimentano correttamente le estensioni enum.
4. Semantic Versioning: `MAJOR. MINOR. PATCH'per artefatti, SDK ed eventi.
5. Automate: schema-differf, linter e test CDC bloccano le modifiche breaking.

Dove memorizzare la versione (meccaniche di indirizzo)

REST/HTTP

versione URI: '/v1/orders ', semplice da instradare, comodo nei gateway. Meno - «blocca» l'evoluzione delle rappresentazioni.
Mediatip/titolo: 'Accept: application/vnd. example. orders. v1 + json "- controllo preciso del formato; Più difficile da fare.
La versione Query: '? api-versione = 1' è utile per A/B, ma è facile da perdere nei cassetti/cassetti.
Raccomandazione: URI per le linee maggiori + feature/capability flags e contenuto-negazionismo per le estensioni minori.

gRPC / Protobuf

Pacchetti/servizi: 'package payments. v1; servizio PaymentsV1; '- linee chiare.
La numerazione dei tag è immutata; i tag eliminati non vengono riutilizzati.
Nuovi campi - 'optional'; breaking nuovo «.v2».

GraphQL

Schema senza maggiore esplicito nell'URL. Evoluzione attraverso @ deprecated e finestre di migrazione; Il «vero» major è il nuovo schema endpoint.
Controllare complexity/depth è parte del contratto.

Event-driven (Kafka/NATS/Pulsar)

Il nome dell'evento è "payment. authorized. v1 'è la versione del tipo.
Registro schemi (Avro/JSON Schema/Protobuf) con modalità di compatibilità (BACKWARD/FORWARD/FULL).
Maggiore per il periodo di transizione.

Modello di versione e criteri di modifica

Semantic Versioning

MAJOR - Modifiche che rompono: rimozione/rinominazione dei campi, cambio delle chiavi di partitura, diverso significato degli stati, maggiore validazione.
MINOR - Additivi: nuovi campi opzionali/endpoint/eventi, nuovi valori enum per tolerant-reader.
PATCH - Correzioni senza modificare il contratto e la semantica.

Deprecation & Sunset

Contrassegna la data obsoleta («Deprecated: true», «@ deprecated»), pubblica la data sunset, l'alternativa e l'hyde della migrazione.
In HTTP, i titoli «Sunset», «Deprecation»; in eventi - separato ".deprecatione. notice`.
Condurre la telemetria usage per decidere il ritiro.

Strategie di versioni per stile

REST

Linee Major su/v1 ,/v2.
MINOR: espansione diagrammi, '? fields =', '? include ='; estensioni enum sicure.
ETAG/If-Match e POST idipotenti per la coerenza senza astinenza.
Errori - Formato stabile ('type', 'code', 'trace _ id').

gRPC

Immettere nuovi servizi/metodi per l'astinenza: 'PaymentsV2. Capture`.
Lo stato degli errori e la semantica deadline sono parte del contratto; Modifica → un nuovo metodo/servizio.
Accetta l'ordine dei messaggi e non cambiarlo in minor.

GraphQL

Aggiungere campi e tipi liberamente; rimuovendo - «@ deprecated» + la finestra di migrazione; Un grande redisine → un nuovo schema ('/graphql-v2 ').
Introspezione e descrizioni - must-have per le migrazioni dei clienti.

Events

Core vs entriched: il nucleo è stabile, l'arricchimento vive vicino e versionata separatamente.
La chiave di partitura è immutata all'interno della linea maggiore.
Migrazioni major - «dual-emit» + migrazione proiezioni/notebook.

Negotion e capability-flag

Capabilities: il client invia «X-Capabilities: risk _ score, price _ v2»; il server risponde con una vista avanzata.
Preferer (HTTP) e "hints'per le risposte parziali.
Nei socket/striam è un messaggio handshake che elenca le estensioni supportate.

Rilascio delle versioni major senza dolore

1. RFC/ADR: perché è necessario un maggiore che si rompe, una matrice di rischi.
2. Dual-run: avvio parallelo "v1" è v2 "(doppia pubblicazione eventi, due gateway root, mirroring del traffico).
3. Adattatori di migrazione proxy/trasmettitori «v1↔v2» per i clienti pesanti.
4. Canario: per gruppo client/topic/tag in gateway.
5. Piano Sunset: data, comunicazione, stand, dati di prova, monitoraggio dell'utilizzo.

Ruoli di piattaforma e infrastruttura

API Gateway/Service Mesh: routing per versione, intestazioni, percorsi; rate-limit и auth per-version.
Schema Registry & Catalog è una fonte di verità per gli speck/diagrammi con la storia dei diffusi.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Osservabilità: la versione deve finire nei fogli/roulotte/metriche.

Test delle versioni

Schema-differf in PR - Blocca breaking.
Consumer-Driven Contracts: il provider viene controllato contro i contratti dei consumatori reali.
Golden sample - risposte di riferimento alla versione.
E2E canarino: confronto tra p95/p99, errori e timeout tra versioni.
Replay eventi: le proiezioni vengono reimpostate su v2 senza soluzione temporanea.

Migrazione dei dati e dei database

Per , le migrazioni dei database sono coordinate tramite expand-and-contract (aggiungi una colonna, inizia a scrivere e la lettura è vecchia).
Per Events: dual-emit e migrazione dei concertatori talvolta, ricarica il cavo su nuove proiezioni.
Non fate «grandi esplosioni».

Relazione con la sicurezza

Scopes per versione: singoli ruoli OIDC/scopes per v1/v2.
I segreti/claim's token sono parte del contratto; il loro turno = maggiore.
PII/PCI - Non espandere payload senza necessità; nuovi campi - con un minimo di privilegi.

Antipattern

Swagger-wash - Specifica aggiornata, nessun server (o viceversa).
Riutilizzare i tag protobuf è una rottura silenziosa dei dati.
Cambiare i significati enum senza maggiore.
Globale «/v2 »« per i cosmetici », versione senza astinenza.
Dimenticati sunset/usage-metriche: impossibile rimuovere la versione precedente in modo sicuro.
Un topic condiviso per i vari major è la miscelazione tra ordine e chiave.

Foglio di assegno prima del rilascio

• Le modifiche sono additive o una linea major separata è stata preparata.
• Lintern e schema-differf verde (breaking non è passato).
• Aggiornati SDK/esempi/documentazione, note sulla compatibilità.
• Attivato tolerant reader nei clienti enum-fallback testato.
• Per major - piano dual-run, adattatori, canarini, date sunset e distribuzione.
• Metriche/logi/trailer contengono la versione e la segmentazione.
• Ci sono lo stand e i set golden per confrontare il v1↔v2.
• Per gli eventi - Registro degli schemi in modalità BACKWARD/FULL, le chiavi di partitura sono invariate.

Esempi di modelli

REST (URI + negotiation)

Percorso: '/api/v2/orders/{ id} '

Заголовок: `Prefer: include=items,customer`, `X-Capabilities: risk_score`

Deprecation: `Sunset: 2026-06-30`, `Link: ; rel="alternate"`

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

Events

`payment. captured. v2 '(kernel) e' payment. enriched. v2 '(parti).
Per il periodo di transizione, il produttore è «v1» e «v2».

FAQ

Quando vuoi esattamente «/v2 »?
Quando gli invarianti/semantici cambiano, eliminano i campi/metodi, cambiano il formato degli identificatori, la chiave di partitura, la SLA/timing in modo che i clienti si rompano.

Puoi vivere senza una versione esplicita di REST?
Solo per i piccoli sistemi. Per le integrazioni esterne, le linee major sono migliori.

Che tempo ha per mantenere una versione obsoleta?
Dipende dall'ecosistema. Per i partner esterni di solito 6-12 mesi con notifica precoce e canarino.

In che modo la versioning degli eventi è diversa dall'API?
Eventi - append-only; nuova semantica = nuovo tipo «.v2» e dual-emit. La chiave di partitura fa parte del contratto.

Totale

Le strategie di versioning sono processo e strumenti: evoluzione additiva predefinita, linee major chiare, capability-negotion, dual-run e sunset. Aggiungete i controlli automatici di compatibilità, la telemetria d'uso e la disciplina della documentazione e le vostre API evolveranno rapidamente, senza migrazioni notturne o cadute inaspettate nei clienti.