Interfejs programistyczny to sposób, w jaki jeden system pyta drugi o dane albo zleca mu operację. Zasada jest prosta, a kłopoty zaczynają się w szczegółach.
Zapytanie i odpowiedź
System pytający wysyła żądanie, system odpowiadający zwraca dane albo potwierdzenie. Odpowiedź zawiera kod mówiący, czy operacja się powiodła — i to on jest podstawą do decyzji o ponowieniu.
Kody dzielą się z grubsza na trzy grupy: potwierdzenie, odmowa z powodu błędu po stronie pytającego i błąd po stronie odpowiadającego. Pierwsza grupa kończy sprawę. Druga oznacza, że dane trzeba poprawić — ponawianie nic nie da. Trzecia to zwykle kłopot chwilowy i wtedy ponowienie ma sens. Integracja traktująca wszystkie błędy tak samo albo zasypuje partnera powtórzeniami, albo porzuca operacje możliwe do dokończenia.
Co sprawdzić w dokumentacji
- sposób uwierzytelnienia i okres ważności poświadczeń,
- limity liczby zapytań,
- format danych i kodowanie znaków,
- sposób obsługi stronicowania przy dużych zbiorach,
- zachowanie przy powtórzeniu tej samej operacji,
- środowisko testowe.
Dwa punkty z tej listy mają na tyle poważne konsekwencje, że warto rozważyć je osobno: przechowywanie poświadczeń oraz praca w granicach limitów.
Stronicowanie
Partner rzadko odda cały katalog w jednej odpowiedzi. Dane przychodzą porcjami, a integracja musi umieć pobrać kolejne. Przerwanie w połowie zostawia zbiór niekompletny, dlatego warto zapisywać, do którego miejsca pobieranie doszło.
Format danych i polskie znaki
Kodowanie znaków to banalny problem, który potrafi zatrzymać wdrożenie. Nazwisko z ogonkiem przesłane w innym kodowaniu wraca jako ciąg znaków zapytania i w takiej postaci trafia na list przewozowy. Warto to sprawdzić od razu na danych z polskimi znakami, a nie na przykładach z dokumentacji.
Podobnie jest z formatem liczb i dat. Partner zwykle oczekuje jednego, ściśle określonego zapisu i odrzuca wszystko inne, czasem bez czytelnego komunikatu. Osobną pułapką są pola o ograniczonej długości: dłuższa nazwa firmy zostaje ucięta po cichu i nikt tego nie zauważy do chwili, w której przesyłka nie dojdzie.
Środowisko testowe
Jego brak oznacza testy na danych produkcyjnych partnera. Przy zamówieniach i płatnościach to sytuacja, w której pierwszy błąd jest widoczny dla klientów.
Powtórzenie operacji
Kluczowe pytanie: co się stanie, jeśli to samo żądanie wyślemy dwa razy? Przy tworzeniu zamówień odpowiedź decyduje o tym, czy po awarii łącza powstaną duplikaty.
Część partnerów pozwala dołączyć do żądania własny identyfikator operacji i sama odrzuca powtórzenia. Jeśli takiej możliwości nie ma, rozpoznawanie duplikatów zostaje po naszej stronie — trzeba zapamiętać, co już zostało wysłane i z jakim skutkiem.
Odpytywanie a powiadomienia
Pytanie partnera co kilka minut jest najprostsze, ale kosztuje zapytania i wprowadza opóźnienie. Tam, gdzie partner na to pozwala, warto rozważyć powiadomienia wysyłane z jego strony.
Dokumentacja bywa nieaktualna
Zachowanie rzeczywiste sprawdza się doświadczalnie, na środowisku testowym. Zgodność z opisem warto potwierdzić, zanim rozwiązanie trafi na produkcję.
Warto też zapisać, co zaobserwowano. Własna notatka o rzeczywistym zachowaniu partnera bywa dokładniejsza niż jego dokumentacja i oszczędza powtórnej analizy przy następnej zmianie.
