API nie jest kompatybilne tylko dlatego, że zachowuje tę samą ścieżkę lub wersję. Konsumenci zależą również od struktury danych, reguł walidacji, wartości domyślnych i zachowania w przypadku błędów. Jeśli różni klienci aktualizują się w różnym tempie, zmiana, która wydaje się niewielka osobie utrzymującej serwer, może przerwać działanie aplikacji mobilnej, integracji zewnętrznej lub procesu wewnętrznego.
Polityka zgodności danych w API PHP przekształca to ryzyko w konkretne decyzje: jakie zmiany są akceptowane, jak są wdrażane i jakie testy trzeba przejść przed wycofaniem kontraktu. Nie ma uniwersalnej reguły, która zapewni kompatybilność każdej zmiany; należy uwzględnić sposób, w jaki każdy konsument odczytuje i wysyła dane.
Kontrakt obejmuje dane, walidację i zachowanie
Kontrakt API obejmuje więcej niż udokumentowany schemat. Składają się na niego pola i ich typy, informacja o tym, czy można je pominąć lub ustawić jako null, sposób interpretowania dat i kwot, wartości akceptowane w żądaniu, format błędów oraz gwarancje dotyczące odpowiedzi. Obejmuje również obserwowalne reguły, takie jak kolejność elementów kolekcji, jeśli klienci od niej zależą, czy stabilność identyfikatora.
W PHP obiekty transferowe, walidatory i serializatory często materializują części tego kontraktu. Przegląd samego kontrolera może nie ujawnić niekompatybilnych zmian w regule walidacji, zasobie odpowiedzi lub mapowaniu między modelem a API. Warto dokumentować kontrakt na podstawie tego, co faktycznie obserwuje klient, a nie wewnętrznej struktury klas lub tabel.
Klasyfikowanie zmian z perspektywy konsumenta
Klasyfikacja jest narzędziem oceny, a nie automatyczną gwarancją. Zmiana addytywna zazwyczaj pozwala nadal działać klientom, którzy ignorują nieznane pola, ale może sprawić, że konsumenci przestaną działać, jeśli konwertują odpowiedź do ściśle określonej struktury lub walidują ją względem zamkniętego schematu. Podobnie nowe opcjonalne pole w żądaniu może być nieszkodliwe dla starszych klientów, podczas gdy uczynienie go obowiązkowym już nie.
- Zazwyczaj addytywne: dodanie opcjonalnego pola do żądania lub odpowiedzi albo dodanie wartości do kolekcji, o ile konsumenci tolerują takie elementy.
- Potencjalnie niekompatybilne: usunięcie lub zmiana nazwy pola, zmiana jego typu, uczynienie pola opcjonalnego obowiązkowym, zmiana formatu błędu lub zmiana znaczenia istniejącej wartości.
- Zależne od kontekstu: zmiana kolejności, precyzji liczbowej, strefy czasowej, semantyki statusu lub kryteriów paginacji. Wynik może się zmienić dla klienta, nawet jeśli schemat pozostaje bez zmian.
Przed zatwierdzeniem zmiany zidentyfikuj konsumentów i sprawdź, jak przetwarzają dane. Nieznane pole może zostać zignorowane, spowodować błąd walidacji albo trafić do logiki, która go nie przewiduje. Nie zakładaj, że wszystkie języki, biblioteki i wersje klientów zareagują tak samo.
Ostrożne rozwijanie żądań i odpowiedzi
W odpowiedziach dodanie pola jest bezpieczniejsze, jeśli uwzględnia się możliwość, że klienci wymagający ścisłego dopasowania odrzucą dodatkowe właściwości. Jeśli zmienia się znaczenie lub typ pola, nie używaj go po cichu ponownie. Wprowadź nowe pole o jasno określonej semantyce, opisz jego relację z poprzednim i utrzymuj oba przez określony okres przejściowy.
W żądaniach kluczowe jest rozróżnienie wartości pominiętej, null i pustej. W PHP walidacja, która traktuje brak klucza tak samo jak jego wartość null, może usunąć dane lub nieoczekiwanie zastosować wartości domyślne. Określ znaczenie każdego przypadku i testuj zarówno nowych, jak i starych klientów. W przypadku nowego pola rozważ początkową akceptację jego braku i przypisanie zgodnego zachowania zamiast wymagania go już przy pierwszym wdrożeniu.
Wersjonowanie ścieżek nie jest jedyną opcją. Kontrakt można rozwijać, zachowując tę samą ścieżkę, jeśli zmiany są kompatybilne, albo opublikować nową wersję, gdy nie są i współistnienie ma sens operacyjny. W obu przypadkach opisz politykę wsparcia: sama etykieta wersji nie informuje, jak długo kontrakt będzie dostępny.
Etapowe wdrażanie bazy danych i API
Bezpieczne wdrożenie oddziela zmiany w warstwie przechowywania od udostępnienia nowego zachowania. Typowa kolejność to rozszerzenie schematu, wdrożenie kodu, który działa zarówno ze starą, jak i nową strukturą, migracja danych, jeśli jest potrzebna, a następnie aktywowanie nowego odczytu lub zapisu. Usunięcie kolumn lub starych ścieżek następuje później, gdy istnieją wystarczające dowody, że nie są już potrzebne.
Takie podejście typu expand-and-contract zapobiega sytuacji, w której wersja aplikacji oczekuje kolumny, która jeszcze nie istnieje, albo nowe wdrożenie przestaje działać ze starszymi procesami. W systemach z wieloma instancjami lub workerami działającymi w tle uwzględnij możliwość współistnienia różnych wersji kodu w trakcie wdrożenia. Migracje muszą być zgodne z takim współistnieniem i mieć strategię odzyskiwania na wypadek niepowodzenia któregoś etapu.
Stopniowe udostępnianie — na przykład włączenie funkcji dla kontrolowanej części konsumentów — może ograniczyć wpływ, ale nie jest równoznaczne z publicznym ujawnieniem ani nie zastępuje zgodności. Stosuj mechanizmy aktywacji, jeśli pozwalają obserwować i wycofać zmianę zachowania; z góry określ warunki zatrzymania dalszego rozszerzania.
Pomiar użycia bez rejestrowania danych wrażliwych
Aby ustalić, którzy konsumenci nadal korzystają z kontraktu, telemetria powinna identyfikować odpowiednią wersję lub funkcję bez przechowywania treści żądań ani odpowiedzi zawierających dane osobowe, dane uwierzytelniające lub informacje handlowe. Rejestruj tylko niezbędne sygnały, takie jak ścieżka, zadeklarowana wersja klienta, wynik i data; ograniczaj dostęp i okres przechowywania stosownie do potrzeb operacyjnych i obowiązujących wymogów.
Sygnał powinien pomagać w podejmowaniu decyzji. Odróżniaj żądania rzeczywistych użytkowników od testów, ponowień lub ruchu automatycznego; obserwuj również błędy, opóźnienia i zmiany natężenia ruchu. Jeśli nie ma wiarygodnego identyfikatora klienta, nie wyciągaj wniosków o jego tożsamości na podstawie danych wrażliwych. Pamiętaj, że proxy, współdzielone klucze i klienci, którzy nie przesyłają informacji o wersji, mogą powodować luki w widoczności.
Wycofanie kontraktu na podstawie weryfikowalnych kryteriów
Nie wycofuj wersji tylko dlatego, że minął ogłoszony termin. Określ sygnały i progi odpowiednie do poziomu ryzyka: utrzymujący się brak identyfikowalnego ruchu, potwierdzona migracja znanych integracji, stabilność następnej wersji oraz procedura wsparcia dla wyjątków. Jeśli utrzymuje się niezidentyfikowany ruch, zbadaj go, zanim uznasz brak identyfikacji za brak użycia.
Z wyprzedzeniem poinformuj, co się zmienia, kogo dotyczy zmiana, jaka jest alternatywa, jakie są planowane terminy i jak przetestować migrację. Udostępnij informacje w dokumentacji dostępnej dla zespołów korzystających z API i zapewnij kanał zgłaszania niezgodności. Jeśli skutków zmiany nie da się szybko odwrócić, rozważ dłuższy okres przejściowy lub tymczasowe współistnienie kontraktów.
Lista kontrolna przed publikacją
- Czy udokumentowano zmieniane pola, typy, możliwość przyjmowania wartości null, wartości domyślne i błędy?
- Czy sprawdzono zachowanie klientów tolerujących i ścisłych wobec nowych lub pominiętych pól?
- Czy testy kontraktowe obejmują znanych konsumentów i przypadki brzegowe walidacji?
- Czy migracja bazy danych umożliwia współistnienie ze starszymi wersjami aplikacji?
- Czy dostępne są wystarczające metryki do wykrywania błędów i użycia kontraktu bez przechwytywania danych wrażliwych?
- Czy określono osoby odpowiedzialne, sposób komunikacji, kryteria wycofania i warunki usunięcia starego rozwiązania?
Przydatna polityka nie obiecuje, że żadna zmiana nie zakłóci działania żadnego klienta. Ujawnia założenia, ogranicza niespodzianki i pozwala działać na podstawie dowodów. Weryfikuj te decyzje przy każdej zmianie kontraktu, zwłaszcza gdy API ma zewnętrznych konsumentów, których cyklu aktualizacji zespół nie kontroluje.
