Dlaczego nigdy nie ufam dokumentacji API

Każdy system e-commerce ma dokumentację swojego API. Base, Sellasist, Fakturownia, inFakt - wszyscy publikują opisy endpointów, parametrów, przykłady zapytań. Wchodzisz, czytasz, piszesz kod. Proste.

Do momentu gdy coś nie działa tak jak jest opisane.

Pracuję z API różnych systemów e-commerce od lat i mogę powiedzieć jedno: dokumentacja to punkt wyjścia, nie źródło prawdy. Prawdziwa wiedza o tym jak API się zachowuje zdobywa się empirycznie - wysyłając zapytania i sprawdzając co wraca.

Oto kilka sytuacji, w których dokumentacja mnie zawiodła - a testy empiryczne uratowały projekt.

Pole, które nie istnieje w dokumentacji, ale działa

Wdrażałem integrację ze sklepem na Sellasist. Klient potrzebował dodatkowych pól w produktach - informacje o dostawcy, waga opakowania, wymiary. Dokumentacja API Sellasist opisuje standardowe pola produktu, ale o polach dodatkowych ani słowa.

Postanowiłem sprawdzić empirycznie. Dodałem pola dodatkowe przez panel administracyjny, a potem spróbowałem je wypełnić przez API. Zadziałało. Wysyłam pole w zapytaniu, wartość się zapisuje, mogę ją odczytać.

Gdybym ufał tylko dokumentacji, napisałbym klientowi “nie da się przez API, trzeba ręcznie”. A da się - po prostu nikt tego nie opisał.

Spędziłem kilka godzin testując różne kombinacje, bo nie miałem pewności który format danych API zaakceptuje. Ale te kilka godzin zaoszczędziło klientowi tygodni ręcznego wpisywania danych.

Pole, które istnieje w dokumentacji, ale nie działa

Odwrotna sytuacja - w tym samym Sellasist. Dokumentacja opisuje pole typu “opcja” w polach dodatkowych produktu. Wygląda idealnie - definiujesz listę wartości, produkt dostaje jedną z nich.

Przetestowałem trzy różne formaty wpisywania wartości. Żaden nie zadziałał poprawnie - system zapisywał albo myślnik, albo myślnik z liczbą, albo pustą wartość. Za każdym razem coś innego, ale nigdy to co chciałem.

Rozwiązanie? Użyłem pola typu “tekst” zamiast “opcja”. Wpisuję wartość jako zwykły string i działa bez problemu. Mniej elegancko, ale niezawodnie.

Gdybym zaufał dokumentacji i pisał całą integrację w oparciu o pole typu “opcja”, straciłbym pewnie dwa dni szukając co robię źle. A problem nie był po mojej stronie.

Liczby, które nie są liczbami

Kolejna historia z Sellasist - pole typu “liczba” w polach dodatkowych. Dokumentacja mówi: wpisz liczbę. Logiczne - wpisuję 5.47, powinienem dostać 5.47.

Dostaję 5.

Okazuje się, że pole “liczba” w Sellasist akceptuje tylko liczby całkowite. Niezależnie od tego czy wyślesz 5.47 jako string, float, z przecinkiem czy z kropką - zawsze dostaniesz zaokrąglenie w dół. A żeby było ciekawiej, pole domyślnie ma ustawioną wartość maksymalną na 0, co oznacza, że każda wpisana liczba jest przycinana do zera.

Spędziłem nad tym pół dnia testując różne formaty, zanim doszedłem do wniosku że to nie bug w moim kodzie. Rozwiązanie: używam pola typu “tekst” i wpisuję liczbę jako string z polskim przecinkiem (“5,47” zamiast 5.47). Działa.

Paginacja, która działa inaczej niż myślisz

To klasyk. Większość API ma paginację - pobierasz dane stronami. W jednym systemie wysyłasz parametr “page=2” żeby dostać drugą stronę. W innym “offset=100” żeby przeskoczyć pierwsze 100 rekordów.

W Sellasist parametr “page” jest opisany w dokumentacji. Wysyłasz “page=2” - i dostajesz… te same dane co przy “page=1”. System po prostu ignoruje parametr. Prawdziwa paginacja działa przez “offset”.

Gdybym nie sprawdził wyników i po prostu iterował po stronach, myślałbym że w systemie jest 100 produktów (ciągle te same). A w rzeczywistości jest ich 5000.

Identyfikator, który ma inną nazwę niż w dokumentacji

Base, Sellasist, Fakturownia - każdy system zwraca identyfikator nowo utworzonego rekordu. Zazwyczaj w polu “id”. Pisząc integrację zakładasz, że po utworzeniu produktu dostaniesz odpowiedź z polem “id” i tę wartość zapiszesz do dalszego użytku.

W jednym z systemów pole nie nazywa się “id” tylko “product_id”. Dokumentacja tego nie precyzuje, a przykłady odpowiedzi są niekompletne. Mój kod szukał pola “id”, nie znajdował go, i zapisywał pustą wartość. Dopiero przy próbie odczytania produktu (gdzie potrzebujesz tego ID) okazywało się, że go nie mam.

Naprawienie tego to zmiana jednej linii kodu. Ale znalezienie przyczyny zajęło mi dobrą godzinę debugowania, bo wszystko wyglądało poprawnie - produkt się tworzył, żadnego błędu, po prostu ID gdzieś ginęło.

Moja zasada pracy z API

Po tych i wielu podobnych doświadczeniach wypracowałem sobie prostą zasadę: dokumentacja mówi co API powinno robić, testy mówią co faktycznie robi.

Przy każdej nowej integracji:

1. Czytam dokumentację - żeby wiedzieć jakie endpointy istnieją i jakich parametrów oczekują.

2. Testuję empirycznie - wysyłam zapytania i sprawdzam co wraca. Szczególnie zwracam uwagę na typy danych, paginację i pola, które powinny działać “oczywiste”.

3. Zapisuję odkrycia - prowadzę notatki z rzeczy, które działają inaczej niż dokumentacja mówi. Przy kolejnej integracji z tym samym systemem nie muszę odkrywać tego na nowo.

4. Nie zakładam niczego - “pole liczbowe” nie musi akceptować ułamków. “Paginacja” nie musi używać parametru “page”. “ID” nie musi być w polu “id”.

To podejście kosztuje dodatkowe godziny przy każdej integracji. Ale oszczędza dni szukania bugów, które bugami nie są - to po prostu rzeczywistość różna od dokumentacji.

Budujesz integrację z API i coś nie działa jak powinno? Napisz - jest spora szansa, że już na to trafiłem i mogę zaoszczędzić Ci czasu.