Czego integrator naprawdę potrzebuje od Twojego API

Większość wpisów na tym blogu pokazuje integrację z konkretnej strony - jak spiąć sklep, system księgowy albo CRM z Fakturownią. Tym razem spojrzenie z drugiej strony: co widzi i czego potrzebuje programista, który integruje się z cudzym API, oraz co z tego wynika dla firmy, która takie API udostępnia innym. Dobre API nie jest kwestią gustu - jego braki kosztują integratora godziny, a firmę wystawiającą API - zgłoszenia i reputację.

Webhooki zamiast odpytywania w pętli

Pierwsze pytanie integratora: czy o zmianie stanu (nowe zamówienie, zmiana statusu, nowa faktura) trzeba się dowiedzieć samemu, odpytując endpoint co kilka minut, czy API samo powiadomi. Odpytywanie w pętli (polling) działa, ale ma koszt po obu stronach: integrator musi wybrać kompromis między opóźnieniem a liczbą zapytań, a serwer obsługuje ruch, który w większości zwraca „nic się nie zmieniło”. Webhook odwraca ten układ - system wysyła powiadomienie, gdy coś faktycznie się wydarzy, więc integrator reaguje od razu, a nie z opóźnieniem wynikającym z częstotliwości odpytywania.

Webhook, który da się realnie używać w produkcji, ma kilka cech, bez których integrator i tak wraca do pollingu jako zabezpieczenia:

• jasno opisany format payloadu i lista zdarzeń, które go wyzwalają,
• podpis powiadomienia (np. nagłówek z sygnaturą), żeby integrator mógł zweryfikować, że webhook faktycznie pochodzi z systemu, a nie od kogoś, kto zgadł adres endpointu,
• ponawianie dostawy przy błędzie po stronie odbiorcy - bez retry jeden padnięty serwer integratora oznacza cicho utracone zdarzenie,
• możliwość ręcznego dociągnięcia stanu przez zwykłe API - webhooki gubią się (padnie serwer, zmieni się adres), integrator musi mieć jak dogonić rzeczywisty stan bez pisania do supportu.

Stronicowanie, które nie zaskakuje

Lista zamówień, faktur czy klientów prędzej czy później przekroczy rozmiar jednej odpowiedzi - pytanie, czy integrator dowie się o tym z dokumentacji, czy z własnej pomyłki na produkcji. Dwie rzeczy psują stronicowanie najczęściej:

• cichy limit per_page, którego nie widać w dokumentacji - integrator ustawia `per_page=500`, dostaje 25 rekordów i zakłada, że to cała lista,
• niejednoznaczny koniec listy - pętla, która kończy się na „odpowiedź krótsza niż per_page”, potrafi urwać się przedwcześnie, gdy akurat ostatnia strona wyszła pełna. Bezpieczny warunek końca to pusta strona albo brak nowych rekordów, nie długość ostatniej odpowiedzi.

Do tego dochodzi stabilność kolejności - jeśli rekordy mogą zmieniać pozycję między stronami (np. przez aktualizację), integrator bez stałego sortowania i kursora opartego o ID albo znacznik czasu może przepisać ten sam rekord dwa razy albo pominąć go całkiem.

Limity, o których integrator wie zawczasu

Rate limiting jest potrzebny - chroni infrastrukturę przed jednym integratorem, który zaleje ją zapytaniami. Problem zaczyna się, gdy integrator dowiaduje się o limicie dopiero po przekroczeniu go, w postaci błędu bez kontekstu. Dobre API mówi o granicach, zanim do nich dojdzie:

• nagłówki z bieżącym stanem limitu (ile zapytań zostało, kiedy licznik się resetuje),
• jasny kod odpowiedzi przy przekroczeniu, z informacją, po jakim czasie można spróbować ponownie,
• osobne, udokumentowane limity dla operacji masowych (eksport, import) - inne niż dla pojedynczych zapytań, bo inaczej integrator i tak znajdzie obejście w postaci setek małych zapytań zamiast jednego dużego.

Czytelne błędy

Błąd, który mówi tylko „422” albo „Wystąpił błąd”, kosztuje integratora czas na zgadywanie, a firmę wystawiającą API - zgłoszenie do supportu, które często sprowadza się do tego samego pytania: które pole i dlaczego. Błąd wart zaufania ma strukturę, nie tylko kod:

• które pole zawiodło i dlaczego (nie tylko „invalid”, ale np. „date musi być w formacie ISO 8601”),
• rozróżnienie błędu po stronie integratora (zły request) od błędu po stronie systemu (coś nie zadziałało mimo poprawnych danych) - integrator musi wiedzieć, czy poprawiać dane, czy ponowić zapytanie,
• ten sam kształt błędu w całym API - inny format odpowiedzi w każdym endpointzie oznacza, że integrator pisze osobną obsługę błędów dla każdego z nich.

Wersjonowanie, które nie psuje integracji z dnia na dzień

Integracja, która działała wczoraj, a dziś się wywraca bez żadnej zmiany po stronie integratora, jest najdroższym scenariuszem - bo szuka się winy tam, gdzie jej nie ma. Dlatego dobre API rozróżnia dwie rzeczy:

• zmiany, które nie łamią istniejących integracji (nowe, opcjonalne pole w odpowiedzi) - mogą wejść bez zapowiedzi,
• zmiany łamiące (usunięcie pola, zmiana typu, zmiana znaczenia statusu) - wymagają nowej wersji API i okresu, w którym stara wersja wciąż działa, żeby integrator zdążył się przepiąć w swoim tempie, a nie w tempie narzuconym przez dostawcę.

Co z tego wynika dla firmy wystawiającej API

Każdy z tych punktów wygląda z perspektywy integratora jak wygoda. Z perspektywy firmy wystawiającej API to coś innego - mniej zgłoszeń do supportu, mniej integracji, które milcząco się psują, i mniej czasu spędzonego na tłumaczeniu tego samego błędu kolejnej osobie przez telefon. Dokumentacja i webhooki, które wyglądają jak koszt na etapie budowy API, zwracają się w momencie, gdy integratorów robi się więcej niż jeden - bo wtedy każda niejasność mnoży się przez liczbę osób, które na nią trafiają.

Podsumowanie

Integrator nie ocenia API po liczbie dostępnych endpointów, tylko po tym, ile razy musiał zgadywać zamiast sprawdzić w dokumentacji. Webhooki zamiast odpytywania w pętli, przewidywalne stronicowanie, limity znane zawczasu, błędy ze strukturą i wersjonowanie, które nie zaskakuje - to różnica między integracją, którą robi się raz, a integracją, do której wraca się co kilka tygodni z tym samym pytaniem. Jeśli planujesz integrację z Fakturownią albo zastanawiasz się, jak wygląda to od strony naszego API - napisz do nas.