Co oznacza API?
API, czyli application programming interface, określa sposób komunikacji między elementami oprogramowania. W integracji internetowej opisuje dostępne operacje, formaty danych, zasady autoryzacji i odpowiedzi. Dzięki API sklep może przekazać zamówienie do systemu magazynowego albo pobrać aktualną dostępność. Nie każde API jest publiczne, bezpłatne ani oparte na tym samym protokole. Wdrożenie zaczyna się od dokumentacji konkretnej usługi i uprawnień do jej użycia.
Kontrakt danych
Ustal wymagane pola, typy wartości, znaczenie identyfikatorów i obsługę pustych danych. Cena bez informacji o walucie i podatku może zostać błędnie zinterpretowana mimo poprawnego formatu JSON. Odróżniaj brak wartości od zera, a lokalną datę od czasu ze strefą. Sprawdź paginację i filtry, aby nie pobrać tylko pierwszej części katalogu. Kontrakt opisuje semantykę, nie jedynie strukturę techniczną wiadomości.
Uwierzytelnianie i bezpieczeństwo
Klucz lub token powinien mieć tylko potrzebne uprawnienia i być przechowywany po stronie właściwego środowiska. Sekret umieszczony w kodzie przeglądarki może odczytać odwiedzający. Ustal rotację, wygasanie i możliwość odwołania dostępu. Logi nie powinny zawierać pełnych tokenów ani zbędnych danych klientów. Szyfrowanie połączenia zabezpiecza transport, ale nie zastępuje kontroli tego, kto może wykonać operację na konkretnym zasobie.
Błędy, limity i ponowienia
Obsłuż limit żądań, przerwy usługi i przekroczenia czasu. Nie ponawiaj bezmyślnie operacji tworzącej zamówienie, jeżeli pierwsza odpowiedź zaginęła: zapis mógł już nastąpić. Klucz idempotencji lub własna deduplikacja pomaga uniknąć duplikatów. Stosuj ograniczone ponowienia i kontrolowany odstęp, a nie nieskończoną pętlę. Rozróżniaj błąd wymagający poprawienia danych od chwilowej awarii, która może ustąpić bez zmiany żądania.
API a webhook
Przy cyklicznym odpytywaniu aplikacja pyta o aktualny stan. Webhook pozwala systemowi źródłowemu powiadomić o zdarzeniu, ograniczając zbędne zapytania. Oba mechanizmy mogą działać razem: powiadomienie sygnalizuje zmianę, a API dostarcza szczegóły i pozwala uzgodnić stan. Żaden nie gwarantuje idealnej kolejności i kompletności bez dodatkowych zasad. Integracja powinna umieć wykryć pominięte dane oraz bezpiecznie je uzupełnić.
Jak utrzymać integrację?
Monitoruj błędy, opóźnienia i zgodność liczby rekordów z oczekiwanym wynikiem. Wersjonowanie API może wymagać zmian po stronie klienta, dlatego obserwuj komunikaty dostawcy i terminy wycofania funkcji. Testuj scenariusze awarii i częściowego sukcesu, nie tylko odpowiedź 200. Poprawne połączenie sieciowe nie dowodzi zakończenia procesu biznesowego. Ostateczną kontrolą jest właściwy stan danych w systemie docelowym i możliwość wyjaśnienia nieudanych operacji.
Przykład niepewnego wyniku zapisu
Aplikacja wysyła żądanie utworzenia zamówienia, lecz połączenie zrywa się przed odpowiedzią. To nie dowodzi, że zapis nie nastąpił. Ponowienie bez kontroli może utworzyć drugi rekord. Ustal z dostawcą mechanizm idempotencji lub sprawdzania wcześniejszej operacji. Odróżniaj operację od pojedynczej próby transmisji i przechowuj bezpieczny identyfikator pozwalający odnaleźć wynik bez ujawniania sekretów.
Obsłuż też częściowy sukces: utworzenie klienta może się udać, a zamówienia już nie. Nie oznaczaj całego procesu jako zakończonego tylko dlatego, że pierwsza odpowiedź miała kod 200. Przy odczycie katalogu sprawdzaj paginację i liczbę rekordów. Poprawny JSON z pierwszą stroną danych potrafi wyglądać wiarygodnie mimo utraty większości asortymentu. Monitoring powinien wykrywać takie rozbieżności, nie jedynie błędy sieciowe.