Zmiana wygląda na drobną: pole „status” zostaje zastąpione przez „state”, typ zmienia się z tekstu na liczbę, a dokumentacja mówi o „uporządkowaniu”. Integracja zwraca 400. AI może zrobić diff i opisać go jako refaktoryzacja. Nie wystarczy.
Analiza zmian API powinna odpowiadać na pytanie o skutek dla klienta, nie tylko o różnicę w plikach. OpenAPI daje strukturę, ale testy potwierdzają zachowanie. Poniższy proces łączy je bez wielkiego aparatu.
Zacznij od dwóch wersji kontraktu
Zachowaj poprzednią specyfikację i nową z wersją, datą i właścicielem. Nie porównuj tylko branchy z nadzieją, że są aktualne. Sprawdź, czy specyfikacja odpowiada produkcji. Dokument może być starszy od zachowania.
Otwórz ścieżki, metody, parametry, requesty, response i wymagania autoryzacji. Nie analizuj tylko endpointów. Jedna zmiana schematu może dotyczyć wielu ścieżek i klientów.
Zapisz klientów i ich wersje. Może jeden używa pola opcjonalnego od lat, inny najnowszego endpointu. Skutek zależy od użycia, a nie tylko od listy zmian.
Diff tekstu jest tylko początkiem
Zwykły diff pokazuje usunięcia i dodatki, ale nie zawsze sens. Zmiana kolejności pól lub opisu może być neutralna. Usunięcie pola jest istotne, kiedy klient go używa. AI powinno pomagać klasyfikować, a nie tylko opisywać linie.
Oceń wpływ nowego endpointu, opcjonalnego parametru lub dodatkowego pola odpowiedzi na konkretnego klienta. Takie zmiany mogą być zgodne, ale nie są automatycznie bezpieczne: klient odrzucający nieznane pola może przestać działać. Przykładem jest schemat JSON z additionalProperties ustawionym na false. Sprawdź rzeczywisty kontrakt i testy integracji, zanim przypiszesz zmianie wagę.
Sprawdź wymagania: czy parametr staje się wymagany, czy typ się zawęża, czy znika wartość enum, czy zmienia się status. To są typowe miejsca złamania kontraktu.
Pola i typy mają rzeczywisty skutek
Zapisz mapę: stare pole, nowe pole, typ, wymagane, użycie i sposób migracji. Jeżeli „status” zmienia się w „state”, nie wystarczy globalna zamiana tekstu. Klient może oczekiwać konkretnych wartości.
Sprawdź daty, walutę, identyfikatory i puste wartości. Tekst „001” nie jest liczbą jeden. Pusta wartość może oznaczać brak, a nie zero. Model nie powinien uzupełniać jej na podstawie podobnych rekordów.
Przy tablicach sprawdź kolejność i obecność elementów. Usunięcie jednego statusu może zmienić całą ścieżkę. Test powinien obejmować prawdziwe odpowiedzi, a nie tylko poprawną specyfikację.
Statusy i błędy są częścią kontraktu
Nowy status 400 zamiast 200 zmienia zachowanie klienta. Opisz, kiedy występuje i co oznacza. Nie przenoś wszystkich problemów w 500, bo łatwiej je zalogować. Klient musi wiedzieć, co zrobić.
Sprawdź timeout, 401, 403, 404, 409, 429 i błędy tymczasowe. Każdy wymaga innej reakcji. Ponowienie powinno mieć limit i ochronę przed duplikatem. Zmiana kodu bez zmiany procesu jest niedokończona.
Dodaj treść błędu i nagłówki. Mogą zawierać informacje o limicie i sposobie powrotu. Nie przechowuj poufnych danych w logach dla łatwiejszej analizy.
Autoryzacja i uprawnienia nie są dodatkiem
Sprawdź, czy zmienia się token, zakres, host, podpis lub rola. Nowa metoda autoryzacji może wymagać nowego procesu, a nie tylko nowego klucza. Nie przechowuj starych tokenów w teście bez daty wygaśnięcia.
Przy mniejszych uprawnieniach sprawdź, czy klient nadal działa. Zmiana roli może blokować odczyt lub zapis. Test powinien obejmować odmowę i poprawny dostęp. Sukces administratora nie wystarcza.
Odwołanie starego klucza wykonaj po przełączeniu i potwierdź odmowę. Nie usuwaj go przed sprawdzeniem zależności. Stare zadania i webhooki mogą używać go nadal.
Test klienta przed publikacją
Przygotuj rzeczywiste żądania dla najważniejszych klientów. Sprawdź poprawny przypadek, brak pola, starą wersję, nową wersję i błąd. Nie testuj tylko Swaggera. To pokazuje skutek.
Porównaj odpowiedź z oczekiwanym kontraktem. Status, typy, pola i wartości powinny być zgodne. Jeżeli nowa wersja ma działać równolegle, test obejmuje obie i ich różnice.
Dodaj powtórzenie po timeout i błędzie integracji. Nie może powstać duplikat. Zapisz identyfikator operacji i wynik. Odbiór dotyczy skutku, a nie tylko kodu odpowiedzi.
Wersjonowanie i okres przejścia
Jeżeli zmiana łamie kontrakt, zaplanuj nową wersję lub okres migracji. Nie ukrywaj jej w drobnym patchu. Klienci potrzebują daty, przykładu i osoby kontaktowej. Dokumentacja ma pokazywać stare i nowe zachowanie.
Opisz deprecation i sunset z datami oraz ograniczeniami. Nie usuwaj starej wersji przed potwierdzeniem migracji klientów. Monitoruj użycie i błędy, ale nie zbieraj danych osobowych dla wygody.
Przygotuj rollback. Powinien przywrócić kontrakt i zachowanie, nie tylko kod. Jeżeli dane zmieniły format, trzeba zaplanować konwersję lub rozdzielenie nowych rekordów.
Komunikat dla klienta bez magii technicznej
Napisz, co się zmienia, jaki jest skutek i co zrobić. Podaj przykład starego i nowego żądania, daty i link do migracji. Nie zaczynaj od „usprawniamy API”. To nie jest informacja.
Dodaj przypadki: usunięte pole, nowy wymóg, nowy status i zmiana tokenu. Klient powinien wiedzieć, czy musi działać i kiedy. Jeżeli nie wpływa na niego, nie wysyłaj alarmu.
Przy większej zmianie przygotuj kontakt i test wspólny. AI może przygotować szkic, ale właściciel potwierdza kontrakt. Nie zgaduj kompatybilności po nazwie wersji.
Analiza logów po wdrożeniu
Sprawdź błędy po kodzie, kliencie i wersji. Nowy problem może dotyczyć jednego klienta, a nie całego API. Zachowaj identyfikatory i czas. Nie wysyłaj pełnych poufnych odpowiedzi do modelu.
Porównaj z poprzednim okresem i wersją. Wzrost 400 może oznaczać złą migrację, ale także nową kampanię. Nie przypisuj przyczyny na podstawie samego trendu.
Po poprawce powtórz zależne żądania i sprawdź publiczne zachowanie. Nie zamykaj tematu samym testem w CI. Potrzebny jest dowód klienta lub kontrolowanego wywołania.
Przykład zmiany pola, która nie jest tylko nazwą
Stara odpowiedź zawiera „status: ready”, nowa zawiera „state: completed”. Diff pokazuje dwie zmiany, ale klient używa tylko statusu do decyzji o wysyłce. Jeżeli przyjmiesz nową wartość bez mapy, raport może oznaczyć gotowy dokument jako inny lub niewłaściwy.
Najpierw zapisz mapę semantyczną: „ready” i „completed” oznaczają gotowe, ale pozostałe wartości nie mają prostego odpowiednika. Wymagaj decyzji właściciela. Nie tłumacz każdego statusu automatycznie.
Test obejmuje gotowy, oczekujący i błędny przypadek. Nowa wersja musi zachować sens, a nie tylko poprawność JSON. Komunikat dla klienta pokazuje mapę i ograniczenie, nie tylko nową nazwę pola. Przy projektowaniu samych pól pomocny jest przewodnik o JSON Schema i walidacji odpowiedzi AI.
Zmiany niewidoczne w specyfikacji
Kontrakt może pozostać taki sam, a integracja i tak się zepsuć. Dostawca skraca limit czasu, zmienia kolejność paginacji, zaczyna odrzucać nieznane pola albo wysyła webhook dwa razy. Diff OpenAPI będzie czysty. Dlatego do analizy dodaj dokumentację, changelog, nagłówki, limity i rzeczywiste odpowiedzi. Specyfikacja opisuje część umowy, nie całe zachowanie systemu.
Sprawdź paginację na pierwszej, środkowej i pustej stronie. Przy sortowaniu zweryfikuj stabilność wyniku po dodaniu rekordu. Jeżeli pobierasz dane przyrostowo, zapisz znacznik i sposób powrotu po błędzie. Jedna powtórzona strona nie powinna tworzyć setki duplikatów, a pominięta nie może znikać bez śladu. Test musi obejmować proces w czasie, nie tylko pojedynczą odpowiedź.
Dodaj przypadek z większym plikiem i wolnym połączeniem. Limit żądania w dokumentacji może być poprawny, ale czas przetwarzania zmieni się po aktualizacji. Timeout klienta powinien prowadzić do sprawdzenia statusu operacji, a nie automatycznego ponowienia zapisu. Ten przypadek bywa ważniejszy dla użytkownika niż elegancka nazwa nowego pola.
Webhooki wymagają osobnego kontraktu
Opisz podpis, kolejność, ponowienia, unikalny identyfikator i oczekiwane potwierdzenie. Nie zakładaj, że zdarzenia przyjdą raz i w kolejności wystąpienia. „Zamówienie opłacone” może wyprzedzić „zamówienie utworzone”, a system odbiorczy musi sobie z tym poradzić bez zgadywania stanu.
Przy zmianie wykonaj test poprawnej sygnatury, błędnej sygnatury, powtórzonego zdarzenia i opóźnionej wiadomości. Zapisz identyfikator oraz wynik przetworzenia. Odpowiedź 200 powinna oznaczać przyjęcie zgodnie z ustalonym procesem, a nie przypadkowe zamknięcie błędu. Jeżeli dane wymagają dalszego pobrania, sprawdź również uprawnienia i brak rekordu.
Stary i nowy format może działać równolegle przez okres przejścia. Mapa wersji powinna pokazywać, który klient otrzymuje który typ zdarzenia. Po migracji potwierdź brak ruchu na starej wersji, zanim ją wyłączysz. Sam brak zgłoszeń klientów nie jest dowodem, że webhooki przestały być potrzebne.
Plan migracji dla jednego klienta
Wybierz integrację o ograniczonym zakresie i zapisz jej używane pola, statusy i role. Uruchom nowy kontrakt na danych testowych, porównaj wynik ze starą wersją i przygotuj przełączenie. Nie zmieniaj jednocześnie modelu AI, schematu bazy i API. Przy awarii chcesz wiedzieć, która warstwa jest podejrzana, zamiast prowadzić śledztwo z trzema nowymi podejrzanymi.
Po przełączeniu sprawdź jedną operację odczytu i jedną zapisu. Odczyt pomaga sprawdzić mapę danych, a zapis uprawnienia i skutek dla tego przypadku. Idempotencję sprawdź osobno: ponów tę samą operację z tym samym kluczem, także po zasymulowanej utracie odpowiedzi, oraz przy równoczesnych próbach. Zweryfikuj skutki lokalne i zewnętrzne, a także to, czy każdy wystąpił tylko raz. Zostaw możliwość powrotu na ograniczony czas. Jeżeli rollback wymaga konwersji danych, przetestuj ją wcześniej; sama możliwość przywrócenia kodu nie cofnie nowych rekordów.
Komunikat zamknij wynikiem: co działa, czego jeszcze nie zmieniono, kiedy stara wersja zostanie wyłączona. Klient powinien dostać przykład migracji i kanał zgłoszenia. Nie wysyłaj samego linku do changeloga z życzeniem miłego dnia. To przenosi całą analizę z powrotem na osobę, której zmiana dotyczy.
Odbiór przez osobę utrzymującą integrację
Poproś programistę lub opiekuna, który nie przygotowywał analizy, o wskazanie skutków na podstawie raportu. Jeżeli widzi tylko listę różnic, ale nie wie, co przetestować, dokument jest niedokończony. Każda istotna zmiana powinna mieć przypadek, właściciela i sposób potwierdzenia.
Sprawdź również fałszywe alarmy. Zbyt wiele neutralnych zmian oznaczonych jako krytyczne sprawia, że zespół ignoruje następny raport. Narzędzie oasdiff pomaga klasyfikować zmiany kontraktu, lecz decyzja o skutku zależy od użycia. Zapisz, które reguły dostosowano i dlaczego. Automatyzacja ma porządkować uwagę, nie produkować cotygodniową burzę w kanale technicznym.
Odbiór kodu i danych przy AI
Nie przesyłaj sekretów i produkcyjnych odpowiedzi do przypadkowego modelu. Użyj fikcyjnych kontraktów i danych testowych. AI może analizować strukturę, ale sekrety powinny pozostać poza kontekstem.
Zapisz, kto zatwierdził specyfikację, test i publikację. Przy pracy agentów sprawdź źródło i zakres ich operacji. Pomocny jest odbiór kodu i poufność agentów AI.
Przy mapie integracji Aeneia Audit pomaga zobaczyć zależności i właścicieli. Testowanie nie kończy się na poprawnym diffie. Ma potwierdzać skutek dla użytkownika.
Kontrakt, którego nikt nie sprawdził na danych testowych, pozostaje hipotezą. Wybierz zależną integrację, zapisz oczekiwany wynik i porównaj odpowiedź po zmianie. Osobno oznacz przypadki, których nie udało się uruchomić.
Sprawdź nas. To zdrowe.
Temat zmienia się szybko. Linki prowadzą do źródeł pierwotnych i stron, na których możesz zweryfikować kontekst.
