API dostawcy zmienia format odpowiedzi: jak przygotować test zgodności integracji

Aplikacja pobiera status zamówienia z systemu dostawcy. Po aktualizacji usługi odpowiedź nadal przychodzi, ale pole z terminem ma inną postać. Na ekranie pojawia się pusta wartość, a zespół dowiaduje się o problemie dopiero od klienta. Sama dostępność API nie oznacza, że integracja nadal rozumie otrzymane dane.

Test zgodności integracji pomaga sprawdzić, czy aplikacja i dostawca nadal używają uzgodnionego formatu oraz czy zmiana nie psuje ważnych scenariuszy. Trzeba jednak określić, co jest przedmiotem umowy między systemami, przygotować przykładowe odpowiedzi i sprawdzić rzeczywiste zachowanie aplikacji. Zielony wynik na fikcyjnym przykładzie nie dowodzi, że usługa produkcyjna działa poprawnie.

Jeśli chcesz uporządkować takie testy, wyślij brief z opisem połączonych systemów, ważnych pól i ostatniej zmiany, którą trudno było ocenić. Wystarczy fikcyjny przykład odpowiedzi. Nie przesyłaj kluczy API ani rzeczywistych danych klientów podczas pierwszej rozmowy.

Ustal, co systemy uzgadniają

Wyobraźmy sobie firmę, której aplikacja pobiera z zewnętrznego systemu numer zamówienia, status i planowany termin. Pracownik korzysta z tych informacji, aby odpowiedzieć klientowi. To przykład projektowy, nie opis konkretnego wdrożenia. Przed napisaniem testu trzeba ustalić, które pola są potrzebne, jak należy je interpretować oraz co zrobić, gdy wartość jest niedostępna.

Kontrakt integracji to uzgodniony opis tego, jak systemy wymieniają informacje. Może obejmować adresy operacji, wymagane pola, format odpowiedzi, błędy i zasady uwierzytelniania. Dokumentacja dostawcy jest punktem wyjścia, ale aplikacja powinna również zapisać własne oczekiwania dotyczące pól, na których opiera działanie użytkownika.

Nie każde pole ma jednakowy wpływ. Zmiana nazwy identyfikatora może uniemożliwić powiązanie sprawy z klientem. Brak opcjonalnego opisu może jedynie wymagać czytelnego komunikatu. Zespół powinien wiedzieć, które wartości są niezbędne do wykonania zadania i jak rozpoznać brak danych bez zastępowania ich przypadkowym wynikiem.

O ustalaniu odpowiedzialności za wartości piszemy w artykule o źródłach danych w integracji systemów. Test formatu nie rozstrzygnie sam, który system jest właścicielem informacji. Najpierw trzeba uzgodnić jej znaczenie i sposób aktualizacji.

Przygotuj odpowiedzi do sprawdzenia

Zestaw testowy powinien obejmować poprawną odpowiedź oraz przypadki istotne dla procesu: brak wartości opcjonalnej, nieznany status, pustą listę i błąd po stronie dostawcy. Jeśli termin może występować w kilku uzgodnionych formatach, przygotujcie przykłady każdego z nich. Nie zakładajcie obsługi wariantu, którego dostawca nie potwierdza w dokumentacji.

Dobrze uwzględnić wartości graniczne i różne jednostki. Liczba zapisana jako tekst może wymagać innej obsługi niż liczba przekazana w polu numerycznym. Data bez strefy może mieć inne znaczenie niż konkretny moment. Aplikacja nie powinna zgadywać znaczenia pola, jeśli zmieniło się ono bez uzgodnienia. Osoba odpowiedzialna powinna otrzymać informację pozwalającą wyjaśnić problem.

Przykłady powinny być wolne od rzeczywistych danych klientów, jeśli nie są one potrzebne do próby. Zespół może przygotować fikcyjne identyfikatory i wartości odpowiadające strukturze odpowiedzi. Ważne, aby próbka odzwierciedlała przypadki spotykane w procesie, a nie wyłącznie najprostszy wzorcowy wynik. O testach bez zmiany danych produkcyjnych piszemy w artykule o środowisku testowym integracji.

Przygotujcie również odpowiedź z dodatkowym polem. W zależności od umowy i używanego klienta taka zmiana może być nieistotna albo ujawnić zbyt sztywne założenie. Nie każda dodatkowa wartość oznacza błąd, ale aplikacja powinna zachować prawidłowe działanie dla danych, których rzeczywiście używa. Oczekiwany wynik trzeba ustalić dla konkretnej integracji.

Sprawdź strukturę i znaczenie

Walidacja struktury może pomóc wykryć brak pola lub nieoczekiwany typ wartości. Nie odpowiada jednak na każde pytanie biznesowe. Status „zakończone” może istnieć w odpowiedzi, a mimo to oznaczać zakończenie innego etapu niż ten, którego oczekuje pracownik. Potrzebne jest porównanie znaczenia z aktualną dokumentacją i uzgodnionym procesem.

Przygotujcie mapę wartości statusów oraz sposób obsługi nowej lub nieznanej wartości. Aplikacja nie powinna przedstawiać nieznanego stanu jako udanej realizacji tylko dlatego, że nie pasuje do żadnej znanej kategorii. Lepszym wynikiem może być informacja o konieczności sprawdzenia i zachowanie oryginalnej wartości w zakresie potrzebnym do wyjaśnienia.

Dokumentacja GitHub dotycząca zmian niezgodnych w REST API podaje przykłady, takie jak usunięcie pola lub zmiana jego typu. To zasady i przykłady dotyczące konkretnego dostawcy. Inne usługi mogą stosować odmienne wersjonowanie i terminy, dlatego należy sprawdzić właściwą dokumentację przed zmianą integracji.

W artykule o konfliktach danych między systemami opisujemy sytuację, w której różne źródła przekazują rozbieżne wartości. Test kontraktu powinien pomóc zauważyć zmianę formatu, ale rozwiązanie konfliktu wymaga dodatkowej reguły biznesowej oraz wskazania osoby odpowiedzialnej.

Obejmij testem zachowanie aplikacji

Sama odpowiedź zgodna ze schematem nie wystarczy. Sprawdźcie, co zobaczy użytkownik: czy właściwy status pojawia się przy odpowiedniej sprawie, czy data ma uzgodnione znaczenie i czy brak wartości nie ukrywa kolejnego kroku. Jeśli aplikacja tworzy powiadomienie lub zapis w innym systemie, próba powinna obejmować również ten etap w bezpiecznym środowisku.

Dodajcie przypadek, w którym dostawca odrzuca żądanie lub odpowiedź dociera z opóźnieniem. Użytkownik powinien wiedzieć, czy jego zadanie zapisano i czy może zamknąć ekran. Zespół obsługi potrzebuje informacji o stanie połączenia oraz identyfikatora sprawy. Nie każda sytuacja wymaga tego samego komunikatu.

Przy ponowieniu operacji sprawdźcie, czy test nie tworzy duplikatu. Pobranie statusu i zapisanie nowego zamówienia mogą mieć różne skutki. W artykule o idempotencji API opisujemy sposób myślenia o powtarzanych żądaniach. Zachowanie konkretnego dostawcy należy potwierdzić w jego dokumentacji i na przygotowanym scenariuszu.

Jeśli odpowiedź wywołuje zmianę w kolejnym systemie, ustalcie, jak rozpoznać przyjęcie komunikatu i potwierdzenie wykonania. O tych etapach piszemy w artykule o API i webhookach. Test powinien pozostawić czytelny wynik także wtedy, gdy jeden z etapów nie powiedzie się w całości.

Porównuj wersje i planuj zmianę

Dostawca może informować o nowej wersji API, zmianie pól albo zakończeniu wsparcia dla dotychczasowego formatu. Zespół powinien wiedzieć, kto obserwuje takie informacje oraz gdzie zapisuje ocenę wpływu na aplikację. Nie wszystkie usługi oferują identyczny harmonogram zmian. Należy sprawdzić aktualne warunki konkretnego dostawcy zamiast zakładać, że każda integracja otrzyma taki sam okres przejściowy.

Przed aktualizacją przygotujcie zestaw odpowiedzi dla obecnej i nowej wersji. Porównajcie pola, błędy oraz zachowanie aplikacji na scenariuszach użytkownika. Jeśli nowa wersja zmienia znaczenie wartości, potrzebna jest decyzja właściciela procesu, a nie jedynie poprawienie nazwy w kodzie. Ustalcie także, kto potwierdzi wynik przed publikacją.

Warto zaplanować powrót do wcześniejszego działania, ale nie zakładać, że zawsze oznacza on proste cofnięcie kodu. Zmiana mogła wpłynąć na zapis danych lub stan zewnętrznego systemu. W artykule o wdrażaniu wersji aplikacji i powrocie opisujemy potrzebę uwzględnienia takich zależności.

Jeśli dostawca nie udostępnia oddzielnego środowiska testowego, zespół powinien ustalić bezpieczny sposób sprawdzenia połączenia oraz ograniczenia takiej próby. Fikcyjna odpowiedź pomaga przetestować zachowanie aplikacji, ale nie potwierdza aktualnego działania usługi produkcyjnej. Te wyniki należy opisywać osobno.

Reaguj na rozbieżności po uruchomieniu

Po publikacji potrzebne są sygnały wskazujące nieoczekiwane odpowiedzi, błędy mapowania oraz sprawy oczekujące na wyjaśnienie. Zespół powinien wiedzieć, kto otrzymuje informację i jak odnajduje konkretną sprawę. Pełna odpowiedź dostawcy może zawierać dane, których nie trzeba zapisywać w każdym dzienniku technicznym.

O sposobie przypisania reakcji piszemy w artykule o monitorowaniu automatyzacji. Przy błędzie formatu warto zachować informacje potrzebne do odtworzenia problemu w odpowiednio chronionym zakresie oraz wskazać wersję integracji. Następnie można przygotować bezpieczny przykład do testu regresji.

Przygotowując dane testowe, ustalcie także, jak traktować wartości, które dostawca może dodać bez zmiany nazwy pola. Lista możliwych statusów bywa rozszerzana wraz z rozwojem usługi. Aplikacja powinna wiedzieć, czy potrafi bezpiecznie pokazać nieznany status, czy musi wstrzymać kolejny krok i przekazać sprawę do wyjaśnienia. Odpowiedź zależy od skutku w danym procesie.

Osobno sprawdźcie odpowiedź zawierającą kilka rekordów, z których jeden ma brakujące pole. Zespół powinien ustalić, czy może przetworzyć pozostałe pozycje, czy cały wynik wymaga kontroli. Częściowe wykonanie musi być widoczne dla obsługi. W przeciwnym razie użytkownik może uznać, że otrzymał kompletną listę, choć jedna sprawa została pominięta.

Jeżeli integracja korzysta z numerów stron wyników lub innego sposobu pobierania dużej listy, sprawdźcie, czy zmiana odpowiedzi nie powoduje pominięcia kolejnych rekordów. Test powinien obejmować więcej niż pierwszą stronę oraz sytuację, w której kolejna część nie dotarła. Zasady pobierania danych należy potwierdzić w dokumentacji konkretnego dostawcy.

Warto przygotować także scenariusz zmiany uprawnień. Odpowiedź o braku dostępu wymaga innej reakcji niż brak rekordu. Aplikacja nie powinna przedstawiać użytkownikowi pustej listy jako dowodu, że żadna sprawa nie istnieje, jeśli nie uzyskała prawa do jej pobrania. Zespół obsługi potrzebuje jasnego rozróżnienia i informacji, do kogo skierować problem.

Przy ocenie raportu z testów zapiszcie wersję dokumentacji, konfigurację klienta oraz datę próby. Jeśli próbka była przygotowana ręcznie, należy to zaznaczyć. Taki zapis pomaga później ustalić, czy porównujecie zachowanie aplikacji z materiałem testowym, czy z rzeczywistą odpowiedzią dostawcy. Oba wyniki są przydatne, ale odpowiadają na różne pytania.

W przypadku zmiany dotyczącej wielu odbiorców warto ustalić kolejność prac i osobę koordynującą kontakt z dostawcą. Zespół może potrzebować wyjaśnienia znaczenia nowego pola albo przykładu błędu, którego nie opisano w dostępnej dokumentacji. Pytanie powinno dotyczyć konkretnej wersji i scenariusza, bez przesyłania danych klientów, które nie są potrzebne do diagnozy.

Po usunięciu problemu przygotujcie test dla przypadku, który go ujawnił, i sprawdźcie sąsiednie scenariusze. Poprawka obsługi jednej wartości nie powinna przypadkowo zmienić interpretacji pozostałych statusów. Osoba odpowiedzialna za proces powinna potwierdzić, czy wynik jest zrozumiały i czy aplikacja nadal prowadzi pracownika do właściwego następnego kroku.

Przy przekazaniu integracji innemu zespołowi zachowajcie opis źródeł i sposobu odtwarzania próby. Dostęp do kluczy należy przekazać uzgodnioną bezpieczną drogą, osobno od przykładów odpowiedzi. Nowa osoba powinna móc rozpoznać, które testy można uruchomić bez wpływu na dane produkcyjne i kto zatwierdza sprawdzenie po stronie dostawcy.

Przed odbiorem uzgodnijcie, które scenariusze mają przejść, kto potwierdza znaczenie danych i jak strony rozpoznają wynik w aplikacji. Artykuł o kryteriach odbioru pomaga zapisać takie oczekiwania. W integracjach systemów zgodność formatu jest potrzebna, ale warto sprawdzić również całą drogę informacji do osoby korzystającej z wyniku.