Tecnologia e Infrastruttura → Versioning API

Versioning API

1) Perché è necessario

• riduce il rischio di incidenti di rilascio
• consente di implementare miglioramenti e sicurezza,
• fornisce alle imprese tempi prevedibili per le migrazioni dei partner.

2) Classificazione delle modifiche

PATCH (non spezzanti) - Correzioni senza modifica del contratto (aggiunta di campi facoltativi, registri di convalida).
MINOR - Estensione back-compatibile (nuovi endpoint, campi default).
MAGGIORE - Modifica della struttura, semantici o rimozione dei campi/endpoint.

Raccomandato «MAJOR». MINOR. PATCH'per gli artefatti (SDK/diagrammi) e il numero API «esterno» può essere semplificato (v1, v2).

3) Modelli di versioning REST

1. IN URI:

`GET /v1/payments/{id}`

Pro: trasparente, cache, facile da instradare. Contro: duplicazione della documentazione, più difficile da evolvere.

2. Nelle intestazioni (content negotion):

`Accept: application/vnd. company. payments. v2+json`

I vantaggi sono la flessibilità, la mancanza di «spazzatura» nell'URL, l'evoluzione del mediatip. Contro - più difficile da ritardare nel browser, serve un cliente disciplinato.

3. Nel titolo di custode:

`X-API-Version: 2` (или `Api-Version: 2025-09-01`)

I vantaggi sono solo sul gateway. Contro - Niente standard, attenzione alla cache.

4. Versione-data (data-based):

Bene per fintech/report: prevedibili «tagli» variazioni (ad esempio trimestrali).

5. Versioning della risorsa/modello:

Raccomandazione per le integrazioni esterne - «URI» + Deprecation/Sunset intestazioni; interno - È possibile «Accept» o titolo versione se il gateway e la piattaforma lo supportano.

4) GraphQL

Preferenza: nessuna versione globale. Evoluzione attraverso l'aggiunta di campi/tipi e la deprecazione ('@ deprecated (reason: "...)').
I cambiamenti che rompono sono solo nelle finestre «grandi» (versioned schema namespace) con l'hide migratorio.
Attenta a «n + 1» e non modificare i campi esistenti.

5) gRPC / Protobuf

I numeri di campo sono invariati. Contrassegnare i campi eliminati comè riserved ".
Aggiungere campi come optional con default sicuro.
Utilizzare il buf breaking/lint per verificare automaticamente la compatibilità.
Versionare pacchetti/moduli: 'package payments. v1;` → `payments. v2`.

6) API eventi (EDA)

Lo schema dell'evento è lo stesso contratto. Memorizzatelo in Schema Registry (Avro/JSON-Schema/Protobuf).
Top e versioni: 'payments. v1. authorized`, `payments. v2. authorized`.
Le modifiche distruttive sono un nuovo tipo di evento o un nuovo topic.
Garanzia di evoluzione: backward-compatibile per i consumatori durante il periodo LTS.

7) Politica di deprecazione e EOL

• Deprecation: etichette in changelog e specifiche (OpenAPI/GraphQL SDL), titolo
• «Deprecation: true» e quando possibile «Sunset: Tue, 31 Mar 2026 00:00:00 GB».
• Comunicazioni: email/portale partner, notifiche webhooks, release note.
• MINOR - 3-6 mesi di supporto, MAJOR - 9-18 mesi (dipende dalle criticità).
• Finestre temporali: fissa in Criteri di versioning API.

8) Routing e rilascio

API Gateway (Kong/Apigee/Nginx/Avvoy) - Regole per il prefisso «/v1/», per titolo o mediatip.

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow: cattura la nuova versione dell '1-5% del traffico, confronta le metriche e i fogli degli errori contrattuali.
Feature Flags - Nascondiamo il comportamento senza modificare il contratto.
Migrazione zero-downtime - Con MAJOR, fornire una doppia scrittura/lettura (dual-write/read) dello schema dati.

9) Contratto-test e controllo di compatibilità

(o swagger- ) - Controlla che MINOR/PATCH non rompa gli schemi.
Spectral linting - Stile, metadati obbligatori (versione, Deprecation).
Consumer-Driven Contracts (Pact) - Garantisce che il provider non comprometta i clienti.
buf breaking для protobuf.
Il CI deve cadere quando si rompe il cambiamento senza aumentare il MAJOR.

10) Documentazione e SDK

Versionare gli specchi: '/docs/api/v1/openapi. json`, `/docs/api/v2/…`.
Generare SDK in versione (npm/maven/pypi) con SemVer e changelog.
Contrassegna i metodi obsoleti con annotazioni/Deprecated SDK.

11) Osservabilità versione

• RPS/latitanza/errore di versione ('api _ version'etichetta).
• Schede di utilizzo degli endpoint: chi altro è su v1?
• Alert: «> 10% 4xx due to contract mismatch», «vecchi client> X% dopo la data T».

12) Cache e versioni

La versione del percorso migliora la cache del CDN.

• `Vary: Accept, X-API-Version`.
• Non modificare la semantica di risposta in MINOR per rompere le chiavi di kash.

13) Sicurezza

Non cifrare o includere la versione in JWT - La versione definisce la query anziché il token.
Non aprire i numeri interni degli assiemi. Utilizzare «v1/v2» nei messaggi esterni.
Con MAJOR, rivedere la validazione, i limiti, la maschera PII.

14) Migrazione e assistenza automatica

Pubblicare «Migration Guide v1 → v2»: tabella delle corrispondenze dei campi, esempi di richieste/risposte, edge-valige.
Offre liner client (CLI) che evidenziano campi obsoleti.
Per i partner di grandi dimensioni, sandbox con due versioni e test dataset.

15) Anti-pattern

«Eternity v1»: assenza di deadline e metriche di utilizzo.
Modifiche distruttive nascoste in MINOR/PATCH.
Versione in query string ('? v = 2') - Rompe la cache e la lettura.
«Un endpoint - Cento valori di flag», difficile da testare/documentare.

16) Assegno-foglio di implementazione

1. È stato selezionato un modello (URI/Accept/Header) per i client interni e esterni.
2. SemVer per specifiche e SDK, breaking-check automatico in CI.
3. Deprecation/Sunset criteri e modelli di comunicazione.
4. Gateway-routing + canarini, dashboard secondo le versioni.
5. CDC/Contract test sulle integrazioni critiche (pagamenti, KYC, report).
6. Documentazione/SDK/Migration Guide pubblicati contemporaneamente al lancio.
7. Un piano EOL con date e responsabilità.

17) Esempi

17. 1 REST (URI + titoli)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 Content Negotion (mediatip)

GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 GraphQL (deprimere il campo)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 gRPC (protobuf)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 Modello evento

• `wallet. v1. balance. updated`
• `wallet. v2. balance. changed '(nuovo evento con schema avanzato)

Gli schemi sono memorizzati in Registry, il produttore non pubblica eventi con uno schema di interoperabilità.

18) Contesto iGaming/Fintech (pratica)

Pagamenti: invio v2 per i nuovi PSP in cui status'/' decline _ reason'esteso; nel gateway mapping v1 v2 per la segnalazione.
KYC: MINOR aggiunge il campo «pep _ screening», i client v1 ignorano, v2 richiede.
Giochi/Limiti: MAJOR cambia il modello dei limiti (giornalieri/settimanali). Doppia esportazione in report fino a EOL v1.
Report ai regolatori: versione-data fissa «reporting-2025-01».

19) Mini-criterio (esempio wiki)

Modello per API esterne - «URI/ vN/»; per interni - 'Accept:... vN+json' o'X-API-Variante: N '.
SemVer: le specifiche e SDK sono pubblicate comè N. minor. patch`. MAJOR richiede RFC/ADR.
Compatibilità MINOR/PATCH - Nessuna modifica compromettente. L'unico modo per rompere è attraverso MAJOR.
Deprecation/EOL: annuncio di ≥90 giorni; Data sunset nelle intestazioni Un ramo LTS per i clienti critici.
Controllo: diff/buf breaking in CI, CDC per le integrazioni chiave.
Osservabilità: metriche/loga con etichetta api _ variante.
Release: canary 5% ≥ 24h, poi graduale al 100% con metriche verdi.

Totale

La versioning non è un «/v2 in URL », ma un processo: regole esplicite per l'evoluzione, controlli automatici di compatibilità, rilasci gestiti e rispetto delle integrazioni. Immettere una politica comprensiva, automatizzare il controllo e l'osservabilità e le modifiche non saranno più una minaccia per il prodotto.