Dodanie pola do odpowiedzi API wygląda niewinnie: niczego nie usuwamy, więc powinno być zgodne wstecz. Powinno. Słowo „powinno” bywa jednak najdroższą częścią projektu integracyjnego.

Cel nauki: odróżnić zgodność opisu i formatu od zgodności działających konsumentów oraz zaplanować zmianę kontraktu na podstawie dowodów.

Trzy warstwy zgodności

WarstwaPytaniePrzykład ryzyka
ŹródłowaCzy kod klienta nadal się kompiluje?Generator SDK zmienia sygnaturę lub typ.
Format przesyłanych danychCzy stary klient potrafi odebrać i zdeserializować nową odpowiedź?Tryb ścisły odrzuca nieznane pole.
SemantycznaCzy klient nadal otrzymuje zachowanie, którego rozsądnie oczekiwał?Nowa wartość enum albo zmieniona wartość domyślna uruchamia złą gałąź logiki.

Google AIP-180 rozdziela właśnie zgodność źródłową, zgodność formatu przesyłanych danych i zgodność semantyczną. Podkreśla też, że katalog zmian zgodnych i niezgodnych jest wskazówką, a nie dowodem dla każdego stosu technologicznego.

Opcjonalne nie znaczy obojętne

Opcjonalne pole żądania oznacza, że stary klient nie musi go wysyłać. Opcjonalne pole odpowiedzi oznacza, że serwer nie zawsze je zwróci. Żadne z tych zdań nie dowodzi jeszcze, że konkretny klient zaakceptuje nieznaną właściwość albo poprawnie obsłuży nową wartość.

Zmiana addytywna jest zwykle bezpieczniejsza od usunięcia pola, ale może ujawnić ukryty kontrakt: ścisłą deserializację, wyczerpujący switch po enumie, limit długości w bazie albo logikę zależną od nieudokumentowanego formatu. Kontrakt API obejmuje zachowanie, nie tylko plik OpenAPI.

Macierz przed wdrożeniem

ZmianaOcena początkowaCo sprawdzić
Nowe opcjonalne pole odpowiedziZwykle addytywnaNieznane pola, generowane modele, proxy i walidatory.
Nowa wartość enum w odpowiedziPodwyższone ryzykoDomyślna gałąź i zachowanie kodu generowanego.
Zmiana wartości domyślnejSemantycznie niezgodnaKlienci, którzy nie wysyłają pola.
Opcjonalne pole staje się wymaganeNiezgodnaWszyscy istniejący producenci żądań.
Zmiana formatu istniejącej wartościSemantycznie ryzykownaParsery, walidacja, indeksy i długości kolumn.

Jak sprawdzić zgodność zmiany API

  1. Określ zasady zgodności. Zapisz, czy aplikacje korzystające z API powinny ignorować nieznane pola w odpowiedzi, czy dopuszczalne jest dodawanie nowych wartości do pól wyliczeniowych (enum) oraz jak długo wspierana jest dana wersja API.
  2. Zrób spis konsumentów. Właściciel, wersja biblioteki, sposób deserializacji i termin aktualizacji są ważniejsze od liczby endpointów.
  3. Testuj reprezentatywne wersje. Odtwórz odpowiedź z nowym polem w testach kontraktowych i uruchom najstarszego wspieranego klienta.
  4. Ogranicz zasięg. Wdróż zmianę etapami, obserwuj błędy deserializacji i miej możliwość wycofania ekspozycji pola.
  5. Wersjonuj, gdy nie można zachować dotychczasowych zasad zgodności. Nowa wersja jest właściwa, gdy nie można zachować zachowania istniejącego kontraktu lub kontrolować aktualizacji konsumentów.
Fikcyjny przykład edukacyjny: serwer dodaje deliveryWindow do odpowiedzi zamówienia. OpenAPI nie oznacza pola jako wymagane, ale starsza aplikacja mobilna odrzuca każdą nieznaną właściwość. Przed szerokim wdrożeniem zespół uruchamia test ze wspieraną wersją klienta, aktualizuje regułę deserializacji i dopiero potem stopniowo udostępnia pole.

Granica tej rady

Nie każda integracja wymaga publicznego wersjonowania. Gdy producent kontroluje wszystkich konsumentów i może wymusić ich jednoczesną aktualizację, prostszy proces może wystarczyć. Nadal trzeba jednak sprawdzić rzeczywisty zestaw wersji podczas wdrożenia. „To tylko pole” nie jest strategią migracji.

Przećwicz decyzję o nowym polu →

Źródła pierwotne (sprawdzone 3.10.2026): Google AIP-180 — Backwards compatibility; Microsoft Azure REST API Guidelines — kontrakty i wersjonowanie. Tabele, przykład i procedura weryfikacji są autorskim opracowaniem edukacyjnym.