Wersjonowanie API
Nadawanie kontraktowi API jawnych wersji, żeby konsumenci mogli przechodzić na nowe we własnym tempie, a stare wycofywać z wyprzedzeniem.
Dodanie opcjonalnego pola rzadko kogoś psuje; zmiana nazwy pola, jego znaczenia albo usunięcie już tak. Wersjonowanie czyni zmiany łamiące zgodność jawnymi: wersja w URL (/v2/), w nagłówku albo wersja z datą przypięta per klient, jak robi to Stripe, ze starymi wersjami tłumaczonymi na bieżący kod przez warstwę zgodności. Wewnątrz jednej firmy zdarzenia i wewnętrzne API potrzebują tej samej dyscypliny, gdy tylko zależy od nich inny zespół.
Wycofanie wersji jest częścią projektu. Nagłówki HTTP Deprecation i Sunset mówią klientom, kiedy wersja jest przestarzała i kiedy przestanie działać. Wielu zmian da się uniknąć bez nowej wersji dzięki expand and contract, a consumer-driven contracts pokazują, kto jeszcze czego używa.
Źródła
- Stripe: APIs as infrastructure: future-proofing Stripe with versioning stripe.com
- RFC Editor: RFC 9745: The Deprecation HTTP Response Header Field rfc-editor.org
- RFC Editor: RFC 8594: The Sunset HTTP Header Field rfc-editor.org
Powiązane hasła
- Expand and contract (migracje bez przestoju): Zmiana schematu bazy w krokach zgodnych wstecz: dodaj nowy kształt, przenieś kod i dane, a stary kształt usuń dopiero później.
- Consumer-driven contracts (testy kontraktowe): Każdy konsument API spisuje, czego faktycznie używa, a build dostawcy sprawdza każdą zmianę względem tych oczekiwań przed wydaniem.
- Open host service (published language): Kontekst upstream udostępnia jeden udokumentowany, stabilny protokół dla wszystkich konsumentów zamiast osobnej integracji dla każdego, często z opublikowanym formatem danych.
- Customer-supplier (upstream i downstream): Relacja dwóch zespołów, w której zespół upstream planuje zmiany z uwzględnieniem potrzeb zespołu downstream, który od niego zależy.
- Tolerant reader (tolerancyjny odbiorca): Konsument API albo zdarzeń czyta tylko potrzebne pola i ignoruje resztę, więc dostawca może dodawać pola, nie psując go.
