Technologia i infrastruktura → API Wersioning

Wersioning API

1) Dlaczego go potrzebujesz

• zmniejsza ryzyko incydentów podczas uwalniania,
• pozwala na zaplanowanie ulepszeń i bezpieczeństwa,
• daje przedsiębiorstwom przewidywalny harmonogram migracji partnerskich.

2) Klasyfikacja zmian

PATCH (nie łamanie): korekty bez zmiany umowy (dodanie pól opcjonalnych, poprawki do walidacji).
MINOR: rozszerzenia kompatybilne z powrotem (nowe punkty końcowe, pola domyślnie).
MAJOR (łamanie): zmiana struktury, semantyki lub usunięcie pól/punktów końcowych.

SemVer 'Major jest zalecany. DROBNE. PATCH 'dla artefaktów (SDK/schematy), natomiast „zewnętrzny” numer API można uprościć (v1, v2).

3) Modele wersji REST

1. DO URI:

„GET/v1/payments/{ id}”

Plusy: przezroczysty, cachable, łatwy w trasie. Wady: powielanie dokumentacji, trudniejsze do subtelnej ewolucji.

2. W nagłówkach (negocjacje treści):

"Akceptuj: wniosek/vnd. przedsiębiorstwo. płatności. v2 + json "

Plusy: elastyczność, brak „śmieci” w adresie URL, wygodna ewolucja typu mediów. Minusy: trudniej jest debugować w przeglądarce, potrzebujesz zdyscyplinowanego klienta.

3. W nagłówku niestandardowym:

„X-API-Wersja: 2” (ила „Api-Wersja: 2025-09-01”)

Plusy: tylko na śluzie. Minusy: brak standardu, ostrożność z pamięci podręcznej.

4. Wersja oparta na dacie:

Dobre dla fintech/sprawozdawczości: przewidywalne „cięcia” zmian (np. kwartalnie).

5. Weryfikacja zasobów/modeli:

Zalecenie: dla integracji zewnętrznych - „URI vN” + Odmowa/nagłówki zachodu słońca; dla wewnętrznych - można 'zaakceptować' lub nagłówek wersji, jeśli brama i platforma obsługują go.

4) GraphQL

Preferencje - brak globalnych wersji. Ewolucja poprzez dodanie pól/typów i depryfikacji ('@ deprecated (powód:... "")').
Zerwanie zmian - tylko w „dużych” oknach (przekrojowy obszar nazw schematów) z przewodnikiem migracji.
Uważaj na „n + 1” i nie zmieniaj znaczenia istniejących pól.

5) gRPC/Protobuf

Numery pola są niezmienne. Zaznacz usunięte pola jako „zarezerwowane”.
Dodaj pola jako opcjonalne z bezpiecznym domyślnie.
Użyj buf breaking/lint do automatycznego sprawdzania zgodności.
Pakiety/moduły wersji: 'płatności pakietowe. v1; płatności „→”. v2 ".

6) API zdarzeń (EDA)

Program imprez jest tą samą umową. Przechowywać w rejestrze schematów (Avro/JSON-Schema/Protobuf).
Tematy i wersje: 'płatności. v1. autoryzowane płatności „,”. v2. autoryzowany ".
Łamanie zmian - nowy typ zdarzenia lub nowy temat.
Gwarancje rozwoju: wstecznie kompatybilne dla konsumentów w okresie LTS.

7) Polityka w zakresie deprymacji i EBI

• Deprecation: etykiety w changelogu i w specyfikacjach (OpenAPI/GraphQL SDL), nagłówek
• „Depresja: prawdziwa” i w miarę możliwości „Zachód słońca: Wt, 31 Mar 2026 00:00:00 GMT”.
• Komunikacja: e-mail/portal partnerski, powiadomienia o hakach internetowych, notatki o wydaniu.
• Warunki: MINOR - 3-6 miesięcy wsparcia, MAJOR - 9-18 miesięcy (w zależności od krytyki).
• Okna czasowe: naprawić w „API Versioning Policy”.

8) Routing i wydania

Gateway API (Kong/Apigee/Nginx/Envoy): zasady według prefiksu '/v1/', nagłówka lub mediatype.

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

Canary/Blue-Green/Shadow: zwiń nową wersję na 1-5% ruchu, porównaj metryki i rejestry błędów kontraktowych.
Flagi funkcji: Ukryj zachowanie bez zmiany umowy.
Migracja zero-przestoju: z MAJOR, zapewnić podwójne zapisywanie/odczytywanie schematu danych.

9) Badanie kontraktu i kontrola zgodności

OpenAPI Diff (lub swagger-diff) - Sprawdź, czy MINOR/PATCH nie łamie schematów.
Spektralne linking - styl, wymagane metadane (wersja, Deprecation).
Umowy konsumenckie (Pact) - gwarantuje, że dostawca nie złamie klientów.
buf łamanie дла protobuf.
CI powinny spaść w łamaniu zmian bez podniesienia MAJOR.

10) Dokumentacja i SDK

Wersja specyfikacji: '/docs/api/v1/openapi. json ', '/docs/api/v2/...'.
Generuj SDK według wersji (npm/maven/pypi) z SemVer i changelog.
Zaznacz metody przestarzałe w SDK z adnotacjami/deprecated.

11) Obserwacja według wersji

• RPS/latency/errors per version (etykieta „api _ version”).
• Mapy użytkowania punktu końcowego: Kto jeszcze jest na v1?
• Wpisy: „> 10% 4xx z powodu niedopasowania kontraktu”, „starzy klienci> X% po dacie T”.

12) Buforowanie i wersje

Wersja tranzytowa poprawia pamięć podręczną CDN.

• 'Vary: Accept, X-API-Version'.
• Nie zmieniaj semantyki odpowiedzi w MINOR, aby złamać klawisze pamięci podręcznej.

13) Bezpieczeństwo

Nie szyfruj ani nie zszywaj wersji do JWT - wersja jest określona przez żądanie, a nie token.
Nie ujawniać numerów montażu wewnętrznego. Użyj „v1/v2” dla wiadomości zewnętrznych.
W MAJOR, weryfikacja walidacji, limity, maskowanie PII.

14) Migracje i auto-pomocnicy

Publikacja „Przewodnik migracyjny v1 → v2”: tabela mapowania pól, przykładowe żądania/odpowiedzi, przypadki krawędzi.
Oferujemy linery dla klientów (CLI), które podkreślają przestarzałe pola.
Dla dużych partnerów - piaskownica z dwiema wersjami i zestawem danych testowych.

15) Anty-wzory

„Wieczny v1”: brak terminów i wskaźników użytkowania.
Ukryte zmiany łamania MINOR/PATCH.
„Wersja w łańcuchu zapytań” ('? v = 2 ') - rozbija pamięć podręczną i czytelność.
„Jeden punkt końcowy to sto wartości flagi”: trudne do przetestowania/udokumentowania.

16) Lista kontrolna wdrażania

1. Wybrany model (URI/Accept/Header) dla klientów zewnętrznych i wewnętrznych.
2. SemVer dla specyfikacji i SDK, automatyczne sprawdzanie w CI.
3. Deprecation/Sunset zasad i szablonów komunikacji.
4. Brama routing + kanary, deski rozdzielcze według wersji.
5. CDC/Testy kontraktowe dla integracji krytycznych (płatności, KYC, sprawozdawczość).
6. Dokumentacja/SDK/przewodnik migracyjny jest publikowany w tym samym czasie co wydanie.
7. Plan EOL z datami i odpowiedzialnością.

17) Przykłady

17. 1 ODPOCZYNEK (URI + nagłówki)

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 Negocjacje w sprawie treści

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

17. 3 GraphQL (deprykacja w terenie)

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 Model zdarzenia

• 'portfel. v1. saldo. zaktualizowany "
• 'portfel. v2. saldo. zmieniony "(nowe zdarzenie z rozszerzonym schematem)

Programy są przechowywane w rejestrze, producent nie publikuje zdarzeń z systemem, który narusza zgodność.

18) Kontekst iGaming/fintech (praktyka)

Płatności: wejście v2 dla nowych dostawców usług płatniczych, w przypadku których rozszerza się „status ”/„ decline _ reason”; na bramce, mapowanie v1 → v2 do raportowania.
KYC: MINOR dodaje pole 'pep _ screening', klienci ignorują v1, v2 - wymaga.
Odpowiedzialne gry/limity: MAJOR zmienia model limitów (dziennie/tygodniowo). Podwójny eksport do raportu przed EOL v1.
Sprawozdawczość dla organów regulacyjnych: stałe wersje-daty: „sprawozdawczość-2025-01”.

19) Mini-polityka (przykład dla wiki)

Model: dla zewnętrznych API - „URI/vN/”; dla wewnętrznych - 'Accept:... vN + json 'lub' X-API-Version: N'.
SemVer: Dane techniczne i SDK są publikowane jako 'N. drobne. patch '. MAJOR wymaga RFC/ADR.
Kompatybilność: MINOR/PATCH - bez zmian. Łamanie → tylko przez MAJOR.
Deprecation/EOL: ≥ 90-dniowe ogłoszenie; Data wygaśnięcia w nagłówkach; Oddział LTS dla klientów krytycznych.
Kontrola: OpenAPI diff/buf breaking w CI, CDC dla integracji kluczowych.
Obserwowalność: mierniki/dzienniki z etykietą „api _ version”.
Uwolnienia: kanarka 5% ≥ 24h, a następnie w etapach do 100% z zielonych metryk.

Wynik

Wersioning nie dotyczy „/v2 w URL „, ale procesu: wyraźnych zasad ewolucji, automatycznych kontroli kompatybilności, zarządzanych wydań i poszanowania integracji. Wprowadź jasną politykę, zautomatyzuj monitorowanie i obserwowalność - a zmiany nie będą już zagrożeniem dla produktu.