Strategii de versionare API

De ce este nevoie de versioning

API se schimbă mai repede decât clienții. Versioning vă permite să eliberați caracteristici și să editați erori fără a rupe integrările, setează ritualul schimbării și face evoluția previzibilă. Cheie: modificări aditive implicite, majoruri - numai pentru rupere, verificări automate ale compatibilității și politici de apus de soare grijulii.

Principii de bază

1. Aditiv-first: noi câmpuri opționale/metode/evenimente - ok; ștergeri și modificări semnificative - majore.
2. MGC (contract minim de garantie) este stabil; îmbogăţire - prin capacităţi/'? include = '.
3. Cititor tolerant: clienții ignoră câmpurile necunoscute și supraviețuiesc corect extensiilor de enum.
4. Versioning semantic: 'MAJOR. MINOR. PATCH "pentru artefacte, SDK, și evenimente.
5. Automate: schema-diff, lintere, și teste CDC bloc modificări de rupere.

În cazul în care pentru a stoca versiunea (mecanica de adresare)

REST/HTTP

URI versiune: '/v1/comenzi '→ ușor de trasat, convenabil în gateway-uri. Minus - „ascunde” evoluția ideilor.
Media/Header: 'Acceptă: cerere/vnd. exemplu. comenzi. v1 + json '- controlul exact al formatului; mai greu de demascat.
Versiunea de interogare: '? api-version = 1 '- convenabil pentru A/B, dar ușor de pierdut în cache-uri/jurnale.
Recomandare: URI pentru linii majore + feature/capability flags și negarea conținutului pentru extensii minore.

gRPC/Protobuf

Pachete/servicii: "pachete de plăți. v1; PaymentsV1 de servicii; "- linii explicite.
Numerotarea etichetelor este neschimbată; etichetele șterse nu pot fi reutilizate.
Câmpuri noi - „opțional”; breaking → new '.v2'.

GraphQL

Schema fără majorări explicite în adresa URL. Evolutie prin ferestre @ depreciate si migrare; „real” major este o nouă schemă criteriu final.
Complexitatea/adâncimea controlului face parte din contract.

Bazat pe evenimente (Kafka/NATS/Pulsar)

Numele evenimentului: 'plata. autorizat. v1 'este versiunea din text.
Registrul schemei (Avro/JSON Schema/Protobuf) cu moduri de compatibilitate (BACKWARD/FORWARD/FULL).
Major → dual-emit „v1” și „v2” pentru perioada de tranziție.

Modelul versiunii și politica de schimbare

Versioning semantic

MAJOR - modificări de rupere: ștergerea/redenumirea câmpurilor, schimbarea cheilor de membru, semnificația diferită a statutelor, strângerea validării.
MINOR - aditiv: noi câmpuri opționale/endpoints/evenimente, noi valori ale enumului cu cititor tolerant.
PATCH - stabilește fără a schimba contractul și semantica.

Depreciere și apus de soare

Mark învechit („Depreciat: adevărat”, „@ depreciat”), publică data apusului, ghidul alternativ și de migrare.
În HTTP - anteturile „Apus de soare”, „Depreciere”; în evenimente - o ".depreciere separată. notificare ".
Telemetrie de utilizare pentru a decide dacă pentru a elimina.

Strategii de versioning după stil

ODIHNĂ

Linii majore pe/v1 ,/v2.
Prelungirea schemei, '? fields = ','? include = '; extensii enum securizate.
ETag/If-Match și POST idempotent pentru consistență non-rupere.
Erori - format stabil ('type', 'code', 'trace _ id').

gRPC

Introducerea de noi servicii/metode de rupere: "PaymentsV2. Capturează.
Stările de eroare și semantica termenului limită fac parte din contract; schimba → noua metoda/serviciu.
Streaming: Conveniți asupra comenzii mesajelor și nu o schimbați în minor.

GraphQL

Adăugați câmpuri și tipuri în mod liber; deletions - prin fereastra „@ depreciated” + migration; reproiectare mare → noua schema ('/graphql-v2 ').
Introspecție și descrieri - must-have pentru migrațiile clienților.

Evenimente

Core vs îmbogățit: miezul este stabil, îmbogățește locuiesc în apropiere și sunt versionate separat.
Cheia de partiție este neschimbată în cadrul liniei majore.
Migrații majore - „dual-emit” + proiecție/migrație a consumatorilor.

Steaguri de negociere și capacitate

Capabilități: client trimite 'X-Capabilities: risk_score,price_v2'; serverul răspunde cu o vizualizare extinsă.
Preferați (HTTP) și sugestii pentru răspunsuri parțiale.
În prize/fluxuri - un mesaj de strângere de mână cu o listă de extensii acceptate.

Eliberarea versiunilor majore fără durere

1. RFC/ADR: de ce este necesar major, ce pauze, matrice de risc.
2. Dual-run: lansarea paralelă a „v1” și „v2” (publicarea de evenimente duble, două direcții de gateway, oglindirea traficului).
3. Adaptoare de migrare: proxy-uri/traducători 'v1↔v2' pentru clienți grei.
4. Canare: dupa grupul de clienti/topic/tag in gateway.
5. Planul Sunset: date, comunicare, standuri, date de testare, monitorizarea utilizării.

Roluri de platformă și infrastructură

API Gateway/Service Mesh: rutare după versiune, antete, trasee; tarif limită и auth per versiune.
Schema Registry & Catalog: Sursa de adevăr pentru specificații/scheme cu istorie difuză.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Observație: versiunea trebuie inclusă în jurnalele/traseele/metrica.

Testarea versiunii

Schema-diff în PR: bloc de rupere.
Contracte bazate pe consumatori: Furnizorul este testat pe contracte reale pentru consumatori.
Eșantioane de aur: răspunsuri de referință la versiuni.
E2E canar: compararea p95/p99, erori și timeout-uri între versiuni.
Replay pentru evenimente: proiecțiile sunt reasamblate la v2 fără discrepanțe.

Migrarea datelor și a bazelor de date

Pentru REST/gRPC: migrările bazelor de date sunt coordonate prin extindere și contract (adăugați o coloană → începeți scrierea → comutați citirea → ștergeți vechiul).
Pentru evenimente: dual-emit și migrația consumatorilor; uneori - reluarea jurnalului pe proiecții noi.
Nu face „explozii mari” - împărțite în trepte cu rollback.

Relația de securitate

Scopuri pentru fiecare versiune: OIDC-scopes individuale/roluri pentru v1/v2.
Secretele/revendicările tokenului fac parte din contract; schimbarea lor = major.
PII/PCI - nu extinde inutil sarcina utilă; domenii noi - cu un minim de privilegii.

Anti-modele

Swagger-wash: caietul de sarcini actualizat, server nu (sau invers).
Reutilizarea etichetelor protobuf este o corupere liniștită a datelor.
Schimbarea sensurilor enum fără majore.
Global '/v2 '„de dragul produselor cosmetice”: o versiune fără a rupe.
Am uitat metricile de apus/utilizare: este imposibil să eliminați versiunea veche în siguranță.
Un subiect comun pentru diferiți majori: un amestec de ordine și chei.

Lista de verificare înainte de lansare

• Modificările sunt aditive sau se prepară o linie majoră separată.
• Linterele și schema-diff sunt verzi (ruperea nu s-a târât).
• Actualizat SDK/exemple/documentație, note de subsol de compatibilitate.
• Activat cititor tolerant pe clienți; enum-rezervă testată.
• Pentru major - plan dual-run, adaptoare, canar, datele de apus de soare și de corespondență.
• Metrics/busteni/trasee conțin o versiune și segmentare de către acesta.
• Există un stand și seturi de aur pentru compararea v1↔v2.
• Pentru evenimente, registrul schemei este în modul BACKWARD/FULL, tastele de partiție sunt neschimbate.

Șabloane de probă

REST (URI + negociere)

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

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

Depreciere: 'Apus de soare: 2026-06-30', 'Legătură: ; rel = "supleant" "

Protobuf/gRPC

proto package payments.v2;

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

Evenimente

"plata. capturat. v2 „(nucleu) și” plată. îmbogățit. v2 '(detalii).
Pentru perioada de tranziţie, producătorul face „v1” şi „v2”.

ÎNTREBĂRI FRECVENTE

Când este nevoie de „/v2 ”?
Când invarianții/semantica se schimbă, câmpurile/metodele sunt eliminate, formatul identificatorilor, cheia de partiționare, SLA/temporizările se schimbă astfel încât clienții să se rupă.

Poți trăi fără o versiune explicită în REST?
Numai pentru sistemele mici. Pentru integrările externe, liniile majore explicite sunt mai bune.

Cât timp pentru a păstra versiunea învechită?
Depinde de ecosistem. Pentru partenerii externi, de obicei 6-12 luni cu notificare timpurie și canar.

Cum este diferită versiunea evenimentului de API?
Evenimente - numai pentru adăugare; noi semantici = nou tip „.v2” și dual-emit. Cheia de partiționare face parte din contract.

Rezultat

Strategiile de versionare sunt procesele și instrumentele: evoluția aditivă implicită, liniile majore clare, capacitatea de negociere, dual-run și apusul soarelui. Adăugați verificări automate de compatibilitate, telemetrie de utilizare și disciplină de documentare - iar API-urile vor evolua rapid, fără „migrații de noapte” și scăderi neașteptate ale clienților.