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.

Autor: zespół Convert Studio — software house z Kielc i Krakowa, projektujemy aplikacje webowe, sklepy i wdrożenia AI dla firm.

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.

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ę.

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".