4 rzeczy, których należy unikać w API HTTP

Tytułem tego artykułu może być równie dobrze „Najgorsze praktyki dla usług webowych”, gdzie przez „usługi webowe” rozumiem elementy, które komunikują się przez HTTP. To dosyć istotne, ponieważ HTTP ma swoją semantykę, na której powinniśmy się opierać, tworząc takie usługi. Jeśli Twoja usługa nie trzyma się ustalonych schematów komunikacji, to w najlepszym razie jest niejasna, a w najgorszym, jej używanie może mieć złe skutki, np. podwójne obciążenie konta klienta czy przekazanie pilotowi samolotu złej ścieżki w czasie lotu.

Porozmawiajmy na szybko o REST

REST (czyli REpresentational State Transfer) to dobry, ale nie jedyny, sposób na tworzenie API. Niektórzy mają problemy z REST-em, dlatego istnieją takie alternatywy jak GraphQl. Szczerze mówiąc, bardzo niewiele API jest w rzeczywistości RESTful. Ogólnie rzecz biorąc, ci, którzy aspirują do bycia RESTful (jak w przypadku API Stripe'a), postępują właściwie, przestrzegając semantyki HTTP. 

Ale przejdźmy już do sedna: oto kilka najgorszych praktyk w zakresie projektowania API opartego o HTTP.

Czasowniki w nazwach zasobów

Zasoby HTTP mają reprezentować coś rzeczywistego (na przykład, użytkownik, karta kredytowa, samochód lub restauracja). Powyższym najlepiej jest nadawać nazwy, które są rzeczownikami. To nie jest losowa decyzja jakiegoś tam programisty, ale przemyślany sposób.

Najgorszą praktyką jest już nazywanie zasobów czasownikami (takim jak „payUser” lub „downloadPdf”), ponieważ powoduje to niepotrzebne zamieszanie. Gdy zestawimy nazwę takiego zasobu i czasownik HTTP uzyskamy GET payUser. Czasownik się powtarza i ciężko odpowiedzieć na pytanie, jaki jest spodziewany rezultat tej akcji.

Tworzenie lub aktualizacja danych poprzez GET

Żądania GET mają ustaloną konwencję:

W szczególności chodzi tutaj o fakt, że metody GET i HEAD nie powinny mieć innego przeznaczenia niż pobieranie informacji. (Źródło: RFC 2616)

Jeśli chcesz mówić w języku internetu (czyli HTTP), lepiej stosować tę konwencję, ponieważ wszyscy tego oczekują. Oczywiście tak samo jest w przypadku PUT, POST itd. ale jest tam też nieco więcej swobody, co byłoby tematem na osobny artykuł.

Wewnętrzna niespójność

Prawdopodobnie najgorszą ze wszystkich praktyk jest tworzenie API tak, że jest niespójne samo w sobie. Na przykład, pobieranie danego użytkownika odbywa się za pomocą samych ścieżek, takich jak /user/{id} (np. http://www.example.org/user/1), ale pobieranie adresu odbywa się już za pomocą parametrów zapytania, takich jak /address?id={id}. Oczywiście doprowadzi to do większego obciążenia poznawczego i będzie frustrować użytkowników Twojego API.

Nieudokumentowane lub niespodziewane zachowanie

Widzi się to najczęściej w wywołaniach API, które nie są idempotentne, ale niespodziewane zachowanie może się również manifestować się w inny subtelny sposób. Na przykład, aktualizowanie użytkownika zmienia dane na jego profilu, ale też nie będzie zaskoczeniem, jeżeli zaktualizowane dane pojawią się w innych miejscach związanych z użytkownikiem. Zakładamy wtedy, że wszystkie miejsca, gdzie dane się zmieniają, pobierają informacje od tego samego API.

Problem może wystąpić, gdy aktualizacja użytkownika zmieniła inny fragment danych, który nie wydaje się powiązany. Na przykład, jeśli adres użytkownika ulegnie zmianie, to czy powinno mieć to wpływ na adresy nieruchomości, które użytkownik posiada?

Niekoniecznie. Czasami mamy do czynienia z czymś bardziej subtelnym niż w powyższym przykładzie. Co, jeśli razem z aktualizacją adresu użytkownika, zaktualizujemy adres przypisany do jego karty kredytowej? To raczej nie jest to, co powinno się stać (skąd wiemy, że akurat zmienił się ich adres rozliczeniowy?), nie bez wyraźnego udokumentowania.

Podsumowanie

Mam nadzieję, że po przeczytaniu tego artykułu, będziecie bardziej czujni i nie popełnicie powyższych błędów.