Tehnologie și infrastructură → API Versioning

Versioning API

1) De ce aveți nevoie de ea

• reduce riscul de incidente în timpul eliberărilor,
• vă permite să programați îmbunătățiri și siguranță,
• oferă întreprinderilor termene previzibile pentru migrațiile partenerilor.

2) Clasificarea modificărilor

PATCH (nu se rupe): corecții fără modificarea contractului (adăugarea de câmpuri opționale, remedieri de validare).
MINOR: extensii back-compatibile (puncte finale noi, câmpuri cu implicit).
MAJOR (rupere): schimbarea structurii, semanticii sau ștergerea câmpurilor/punctelor finale.

SemVer 'MAJOR este recomandat. MINOR. PATCH "pentru artefacte (SDK/scheme), în timp ce numărul API" extern "poate fi simplificat (v1, v2).

3) Modele de versionare REST

1. PENTRU URI:

'GET/v1/payments/{ id}'

Pro: transparent, cachable, ușor de traseu. Contra: duplicarea documentației, mai dificil de evoluat subtil.

2. În anteturi (negocierea conținutului):

"Accept: cerere/vnd. companie. plăți. v2 + json '

Pro: flexibilitate, fără „gunoi” în URL, evoluție convenabilă a tipului media. Contra: este mai dificil să depanați în browser, aveți nevoie de un client disciplinat.

3. În antetul personalizat:

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

Pro: doar pe feluice. Contra: fără standardizare, atent cu memoria cache.

4. Versiune bazată pe date:

Bun pentru fintech/raportare: „reduceri” previzibile ale schimbării (de ex. trimestrial).

5. Resource/Model Versioning:

Recomandare: pentru integrări externe - anteturi „URI vN” + respingere/apus de soare; pentru intern - puteți „Accept” sau antetul versiunii, dacă gateway-ul și platforma îl suportă.

4) GraphQL

Preferință - fără versiuni globale. Evolutia prin adaugarea de domenii/tipuri si depractie ('@ depreciated (motiv:... "")').
Modificări de rupere - numai în ferestre „mari” (namespace schema versioned) cu ghid de migrare.
Urmăriți „n + 1” și nu modificați sensul câmpurilor existente.

5) gRPC/Protobuf

Numerele de câmp sunt imuabile. Marcați câmpurile șterse ca „rezervate”.
Adăugați câmpuri ca opționale cu implicit în condiții de siguranță.
Utilizați ruperea/scame buf pentru verificarea automată a compatibilității.
Versiune pachete/module: "pachete de plăți. v1, „→” plăţi. v2 '.

6) API-uri pentru evenimente (EDA)

Schema de evenimente este același contract. Păstrați-l în Registrul Schema (Avro/JSON-Schema/Protobuf).
Subiecte și versiuni: "plăți. v1. plăți autorizate „,”. v2. autorizat ".
Modificări de rupere - un nou tip de eveniment sau un nou subiect.
Evolutia garanteaza: inapoi-compatibil pentru consumatori in perioada LTS.

7) Politica de depricție și EOL

• Depreciere: etichete în changelog și în specificații (OpenAPI/GraphQL SDL), antet
• "Depresie: true 'și când este posibil" Apus de soare: Tue, 31 Mar 2026 00:00:00 GMT ".
• Comunicații: portal de e-mail/partener, notificări de carti web, note de lansare.
• Termeni: MINOR - 3-6 luni de sprijin, MAJOR - 9-18 luni (în funcție de critică).
• Ferestre de timp: fixați în „Politica de versioning API”.

8) Rutare și versiuni

Gateway API (Kong/Apigee/Nginx/Envoy): reguli prin prefix '/v1/', prin antet sau mediatip.

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

Canary/Blue-Green/Shadow: rulați noua versiune pe 1-5% din trafic, comparați valorile și jurnalele erorilor contractuale.
Feature Flags: Ascundeți comportamentul fără a schimba contractul.
Zero-downtime migrare: cu MAJOR, oferi dual-write/citire a schemei de date.

9) Testarea contractelor și controlul compatibilității

OpenAPI Diff (sau swagger-diff) - Verificați dacă MINOR/PATCH nu rupe scheme.
Spectral linting - stil, metadate necesare (versiune, depreciere).
Contracte bazate pe consumatori (Pact) - asigură că furnizorul nu rupe clienții.
buf rupere для protobuf.
CI ar trebui să scadă în modificări de rupere, fără a ridica MAJOR.

10) Documentație și SDK

Versiunea specificațiile: '/docs/api/v1/openapi. json ', '/docs/api/v2/...'.
Generați SDK după versiune (npm/maven/pypi) cu SemVer și changelog.
Marcați metode depreciate în SDK cu/adnotări depreciate.

11) Observarea după versiune

• RPS/latență/erori pe versiune (etichetă „api _ version”).
• Hărți de utilizare a punctului final: Cine altcineva este pe v1?
• Alerte: „> 10% 4xx din cauza neconcordanței contractuale”, „clienți vechi> X% după data T”.

12) Caching și versiuni

Versiunea în tranzit îmbunătățește cachability CDN.

• „Vary: Accept, X-API-Version”.
• Nu schimbați semantica răspunsului în MINOR pentru a sparge tastele cache.

13) Siguranță

Nu cripta sau cusatura versiunea în JWT - versiunea este determinată de cerere, nu token.
Nu dezvălui numere interne de asamblare. Utilizați „v1/v2” pentru mesaje externe.
În MAJOR, validarea revizuirii, limitele, mascarea PII.

14) Migrații și auto-ajutoare

Publicați „Ghidul de migrare v1 → v2”: tabelul de cartografiere a câmpului, cererile de eșantionare/răspunsurile, cazurile de margine.
Oferim lintere pentru clienți (CLI) care evidențiază câmpurile învechite.
Pentru parteneri mari - sandbox cu două versiuni și un set de date de testare.

15) Anti-modele

„Eternul v1”: lipsa termenelor limită și a metricii de utilizare.
Modificări ascunse de rupere în MINOR/PATCH.
„Versiune în șir de interogare” ('? v = 2 ') - sparge memoria cache și lizibilitatea.
„Un punct final este o sută de valori de pavilion”: dificil de testat/document.

16) Lista de verificare a implementării

1. Modelul selectat (URI/Accept/Header) pentru clienții externi și interni.
2. SemVer pentru specificații și SDK, verificare automată de rupere în CI.
3. Politica de depreciere/apus de soare și șabloane de comunicare.
4. Gateway routing + canare, tablouri de bord după versiune.
5. Teste CDC/Contract pentru integrări critice (plăți, KYC, raportare).
6. Ghidul de documentare/SDK/migrare este publicat în același timp cu lansarea.
7. Planul EOL cu date și responsabil.

17) Exemple

17. 1 REST (URI + antete)

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 Negocierea conținutului

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

17. 3 GraphQL (Depriction câmp)

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 Modelul evenimentului

• "umed. v1. echilibru. actualizated '
• "umed. v2. echilibru. schimbat "(eveniment nou cu schemă extinsă)

Schemele sunt stocate în Registru, producătorul nu publică evenimente cu un sistem care încalcă compatibilitatea.

18) Context iGaming/fintech (practică)

Plăți: intrare v2 pentru noile PSP-uri în care se extinde „status ”/„ decline _ reason”; pe poarta de acces, cartografiere v1 → v2 pentru raportare.
KYC: MINOR adaugă câmpul „pep _ screening”, clienții ignoră v1, v2 - necesită.
Jocuri/limite responsabile: MAJOR modifică modelul de limite (zilnic/săptămânal). Export dublu la raportare înainte de EOL v1.
Raportarea către autoritățile de reglementare: versiuni-date fixe: „raportare-2025-01”.

19) Mini-politică (exemplu pentru wiki)

Model: pentru API-uri externe - „URI/vN/”; pentru intern - "Accept:... vN + json "sau" X-API-Version: N ".
SemVer: Specificațiile și SDK-urile sunt publicate ca 'N. minor. patch-uri ". MAJOR necesită RFC/ADR.
Compatibilitate: MINOR/PATCH - fără modificări de rupere. Spargerea → doar prin MAJOR.
Deprecierea/EOL: anunțul de ≥90 zile; Data de apus în titluri; Filiala LTS pentru clienții critici.
De control: OpenAPI diff/buf rupere în CI, CDC pentru integrări cheie.
Observabilitate: valori/busteni cu eticheta 'api _ version'.
Versiuni: canar 5% ≥ 24h, apoi în etape la 100% cu metrici verzi.

Rezultat

Versionarea nu este despre „/v2 în URL „, ci despre proces: reguli explicite de evoluție, verificări automate ale compatibilității, versiuni gestionate și respectarea integrărilor. Introduceți o politică clară, automatizați monitorizarea și observabilitatea - iar schimbările nu vor mai reprezenta o amenințare pentru produs.