Wersjonowanie API — jak rozwijać interfejs, nie psując integracji
Interfejs programistyczny, z którego korzysta choć jeden zewnętrzny system, przestaje być wyłącznie Twoim kodem. Staje się umową. Każda zmiana w nazwie pola, formacie daty czy znaczeniu kodu odpowiedzi może zatrzymać sklep partnera, synchronizację z magazynem albo aplikację mobilną, której nie da się zaktualizować w jeden dzień. Wersjonowanie to sposób na rozwijanie tej umowy bez zrywania jej jednostronnie.
Krótka odpowiedź: wersjonowanie API polega na tym, że zmiany niezgodne wstecz — usunięcie pola, zmiana typu, zmiana znaczenia — wprowadza się w nowej wersji interfejsu, a stara działa równolegle przez zapowiedziany okres. Zmiany zgodne wstecz, takie jak dodanie opcjonalnego pola, wprowadza się bez nowej wersji.
Najważniejsza decyzja nie dotyczy formatu numeru wersji, lecz tego, jak długo utrzymujesz starą wersję i jak informujesz o jej wycofaniu.
Dlaczego to w ogóle problem
Po stronie serwera zmiana jest natychmiastowa: wdrażasz nowy kod i wszystko działa po nowemu. Po stronie korzystających systemów zmiana wymaga ich aktualizacji — a te należą do innych zespołów, innych firm, a w przypadku aplikacji mobilnych leżą na telefonach użytkowników, którzy aktualizują je, kiedy chcą.
Oznacza to, że przez pewien czas — tygodnie, miesiące, czasem dłużej — Twój serwer musi obsługiwać klientów, którzy oczekują starego zachowania. Wersjonowanie jest formalnym sposobem na zarządzanie tym okresem.
Które zmiany są bezpieczne
Punktem wyjścia jest rozróżnienie zmian zgodnych i niezgodnych wstecz. To ono decyduje, czy potrzebna jest nowa wersja.
| Zmiana | Zgodna wstecz? | Uwagi |
|---|---|---|
| Dodanie nowego punktu dostępu | Tak | Istniejący klienci go nie używają |
| Dodanie opcjonalnego pola w odpowiedzi | Tak | Pod warunkiem, że klienci ignorują nieznane pola |
| Dodanie opcjonalnego parametru zapytania | Tak | Wartość domyślna musi zachować stare zachowanie |
| Nowa wartość w polu wyliczeniowym | Ryzykowna | Klient może nie obsłużyć nieznanej wartości |
| Usunięcie pola z odpowiedzi | Nie | Klient korzystający z pola przestaje działać |
| Zmiana nazwy pola | Nie | Dla klienta to usunięcie i dodanie |
| Zmiana typu lub formatu | Nie | Liczba jako tekst, inny format daty |
| Nowe pole obowiązkowe w zapytaniu | Nie | Stare zapytania zaczynają być odrzucane |
| Zmiana znaczenia istniejącego pola | Nie | Najgroźniejsza — nie wywołuje błędu, tylko złe dane |
| Zaostrzenie walidacji | Nie | Dotąd akceptowane dane zaczynają być odrzucane |
Uwaga praktyczna: najgroźniejsza jest zmiana znaczenia pola przy zachowaniu jego nazwy i typu — na przykład gdy kwota zaczyna być podawana netto zamiast brutto. Integracja nie zgłasza błędu, tylko po cichu przetwarza złe dane. Takie zmiany zawsze wymagają nowego pola albo nowej wersji, nigdy modyfikacji w miejscu.
Sposoby oznaczania wersji
Wersja w adresie
Numer wersji stanowi część ścieżki. Rozwiązanie najprostsze i najbardziej czytelne: od razu widać, z której wersji korzysta dany klient, łatwo przekierować ruch i łatwo buforować. Wada — adres zasobu zmienia się między wersjami, co puryści uznają za niezgodne z zasadami projektowania interfejsów. W praktyce to najczęściej wybierany wariant.
Wersja w nagłówku
Adres pozostaje stały, a klient wskazuje wersję w nagłówku zapytania. Czystsze koncepcyjnie, ale trudniejsze do diagnozy — z samego adresu w dzienniku nie widać, której wersji użyto, a narzędzia pośredniczące i buforujące muszą uwzględniać nagłówek.
Wersja jako parametr zapytania
Kompromis między powyższymi. Łatwy do testowania w przeglądarce, ale łatwy też do pominięcia — klient, który zapomni o parametrze, dostaje wersję domyślną, a ta z czasem się zmienia.
Wersjonowanie po dacie
Zamiast numerów stosuje się datę wydania. Klient przypina się do konkretnej daty i dostaje zachowanie z tego dnia. Rozwiązanie wygodne przy częstych drobnych zmianach, ale wymagające dyscypliny w utrzymywaniu wielu wariantów zachowania jednocześnie.
Zasady, które oszczędzają kłopotów
- Wersjonuj od pierwszego wydania. Dodanie wersji do interfejsu, który jej nie miał, samo w sobie jest zmianą niezgodną wstecz.
- Grupuj zmiany niezgodne. Każda nowa wersja to koszt utrzymania. Lepiej wydać jedną dopracowaną niż pięć drobnych.
- Dodawaj zamiast zmieniać. Nowe pole obok starego pozwala na łagodne przejście bez nowej wersji.
- Klienci ignorują nieznane pola. Zapisz to w dokumentacji jako wymóg — inaczej każde dodanie pola będzie ryzykowne.
- Nie zmieniaj zachowania wersji już wydanej. Poprawka błędu, która zmienia wynik, bywa dla klienta zmianą niezgodną.
- Jedna wersja domyślna, jasno opisana. Klient bez wskazania wersji musi wiedzieć, co dostanie.
- Testy kontraktowe. Automatyczne sprawdzenie, czy odpowiedzi starej wersji wyglądają tak samo po każdym wdrożeniu.
Wycofywanie starej wersji
Utrzymywanie wersji bez końca jest równie szkodliwe jak ich brak. Każda aktywna wersja to kod, testy i przypadki do obsługi przy każdej zmianie. Proces wycofania warto opisać, zanim wydasz drugą wersję.
| Etap | Co robisz | Sygnał dla klienta |
|---|---|---|
| Zapowiedź | Ogłoszenie daty wycofania i ścieżki migracji | Komunikat bezpośredni i w dokumentacji |
| Oznaczenie | Odpowiedzi starej wersji niosą informację o wycofaniu | Nagłówek z datą zakończenia wsparcia |
| Monitoring | Obserwacja, kto nadal korzysta ze starej wersji | Kontakt indywidualny z największymi klientami |
| Przerwy próbne | Krótkie, zapowiedziane wyłączenia | Klienci, którzy przegapili zapowiedź, zauważają problem |
| Wyłączenie | Stara wersja zwraca czytelny błąd z odesłaniem do nowej | Kod błędu i adres dokumentacji migracji |
Okres przejściowy zależy od tego, kim są klienci. Dla wewnętrznych systemów wystarczą tygodnie. Dla partnerów zewnętrznych — miesiące. Dla aplikacji mobilnych trzeba uwzględnić użytkowników, którzy nie aktualizują aplikacji latami, i zdecydować, czy wymusić aktualizację.
Wiedza o tym, kto z czego korzysta
Nie da się rozsądnie wycofać wersji, nie wiedząc, kto jej używa. Minimum to identyfikacja klienta przy każdym zapytaniu — kluczem dostępu lub tokenem — oraz zapis wersji w dzienniku.
- Liczba zapytań na wersję w czasie — pokazuje tempo migracji.
- Lista klientów na starej wersji — z danymi kontaktowymi do bezpośredniej rozmowy.
- Wykorzystanie poszczególnych pól — czasem okazuje się, że pole planowane do usunięcia nie jest używane przez nikogo i można je usunąć bez nowej wersji.
Dokumentacja i komunikacja
Wersjonowanie bez dokumentacji jest tylko numeracją. Klient musi wiedzieć, co się zmieniło, dlaczego i co ma zrobić.
- Rejestr zmian z datą, wersją i wskazaniem, czy zmiana jest zgodna wstecz.
- Przewodnik migracji dla każdej zmiany niezgodnej — konkretnie, które pola zmienić i jak.
- Specyfikacja w formacie maszynowym, z której klienci mogą generować kod — opisaliśmy to w materiale o dokumentacji API.
- Kanał powiadomień dla osób technicznych po stronie partnerów — lista mailingowa lub strona statusu.
- Środowisko testowe z nową wersją dostępne przed jej produkcyjnym wydaniem.
A jeśli API ma tylko jednego klienta?
Gdy interfejs obsługuje wyłącznie własną aplikację webową wdrażaną razem z serwerem, formalne wersjonowanie bywa zbędne — obie strony zmieniają się jednocześnie. Sytuacja zmienia się w momencie pojawienia się aplikacji mobilnej, integracji z systemem partnera albo drugiego zespołu korzystającego z interfejsu. Warto przewidzieć ten moment i zaprojektować strukturę adresów tak, żeby dodanie wersji nie wymagało przebudowy.
Przy integracjach z systemami zewnętrznymi warto też zajrzeć do materiału o webhookach, bo zmiany w formacie powiadomień podlegają tym samym zasadom. Więcej o budowie systemów integrujących się z otoczeniem znajdziesz na stronie aplikacje webowe.
Najczęstsze błędy przy wersjonowaniu
- Nowa wersja dla każdej zmiany. Po roku istnieje osiem wersji, z których żadnej nie da się wyłączyć, bo każdą ktoś używa.
- Kopiowanie całego kodu dla nowej wersji. Poprawka błędu musi być potem wprowadzana w kilku miejscach. Lepiej utrzymywać wspólną logikę i różnicować wyłącznie warstwę odpowiedzi.
- Brak daty wycofania przy wydaniu. Wersja wydana bez zapowiedzi końca wsparcia jest w praktyce utrzymywana bezterminowo.
- Zmiana wersji domyślnej bez ostrzeżenia. Klienci niewskazujący wersji dostają nagle inne zachowanie.
- Dokumentacja tylko najnowszej wersji. Partner korzystający ze starszej nie ma do czego zajrzeć.
Wspólną przyczyną tych błędów jest traktowanie wersjonowania jako decyzji technicznej, a nie organizacyjnej. Numer wersji jest najprostszą częścią — trudniejsze jest ustalenie, kto decyduje o wydaniu nowej, jak długo trwa wsparcie i kto rozmawia z partnerami.
Warto też pamiętać, że wersjonowanie nie zwalnia z dbania o stabilność w obrębie jednej wersji. Partner, który raz zintegrował się z interfejsem, oczekuje, że będzie on działał tak samo przez cały zapowiedziany okres wsparcia — łącznie z formatem błędów, limitami zapytań i czasem odpowiedzi.
Podsumowanie
API, z którego korzysta choć jeden zewnętrzny system, jest umową, a nie wewnętrznym szczegółem implementacji. Wersjonowanie pozwala tę umowę rozwijać: zmiany zgodne wstecz wprowadza się swobodnie, niezgodne — w nowej wersji działającej obok starej przez zapowiedziany czas.
Jeśli budujesz interfejs od zera, oznacz wersję w adresie od pierwszego wydania i zapisz w dokumentacji wymóg ignorowania nieznanych pól. Te dwie decyzje kosztują kilka minut, a oszczędzają najtrudniejszych rozmów z partnerami — tych, które zaczynają się od zdania „od wczoraj nic nam nie działa".
Najczęstsze pytania
Przy każdej zmianie niezgodnej wstecz: usunięciu lub zmianie nazwy pola, zmianie typu albo formatu danych, dodaniu obowiązkowego parametru, zaostrzeniu walidacji lub zmianie znaczenia istniejącego pola. Dodanie opcjonalnego pola lub nowego punktu dostępu nie wymaga nowej wersji.
Najczęściej wybieranym i najbardziej praktycznym rozwiązaniem jest numer w adresie, bo od razu widać wersję w dziennikach i łatwo kierować ruchem. Wersja w nagłówku jest czystsza koncepcyjnie, ale trudniejsza w diagnozie. Ważniejsza od formatu jest konsekwencja i jasno opisana wersja domyślna.
Zależy od klientów: przy systemach wewnętrznych wystarczą tygodnie, przy partnerach zewnętrznych miesiące, a przy aplikacjach mobilnych trzeba uwzględnić użytkowników, którzy nie aktualizują aplikacji. Kluczowe jest zapowiedzenie daty wycofania z wyprzedzeniem i monitorowanie, kto nadal korzysta ze starej wersji.
Zmiana znaczenia pola przy zachowaniu jego nazwy i typu, na przykład podawanie kwoty netto zamiast brutto. Integracja nie zgłasza wtedy żadnego błędu, tylko po cichu przetwarza nieprawidłowe dane. Taką zmianę zawsze wprowadza się jako nowe pole lub w nowej wersji.
Gdy interfejs obsługuje wyłącznie własną aplikację webową wdrażaną razem z serwerem, formalne wersjonowanie bywa zbędne. Staje się konieczne w momencie pojawienia się aplikacji mobilnej, integracji partnera lub drugiego zespołu, dlatego warto od początku projektować adresy tak, by wersję dało się łatwo dodać.
Bezpłatna wycena Twojego projektu
Opisz w kilku zdaniach, co chcesz zbudować — stronę, aplikację czy sklep. Odpowiadamy w ciągu 24 godzin roboczych konkretną propozycją zakresu i harmonogramu. Konsultacja i wycena są bezpłatne, bez zobowiązań.