5.05.20203 min

Scott ShippSenior Software Engineer

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

Dowiedz się, jakich zachowań i praktyk należy unikać przy projektowaniu API opartego o HTTP.

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.

<p>Loading...</p>

Powiązane artykuły

Dziel się wiedzą ze 160 tysiącami naszych czytelników

Zostań autorem Readme

Hitachi Energy

Security Architect

senior

15 000 - 21 000 PLN

Umowa o pracę

Kraków

Praca zdalna 100%

Ważna do 26.02.2022

Bardzo dobrze
Microsoft Azure and/or AWS

Hitachi Energy

Product Development Manager

senior

15 000 - 20 000 PLN

Umowa o pracę

Kraków

Praca zdalna 100%

Ważna do 26.02.2022

Bardzo dobrze
AgileSoftware Development Life Cycle Leadership skills

Simple SA

Java Developer (Mid/Senior)

medium

7 000 - 15 000 PLN

Kontrakt B2BUmowa o pracę

Praca zdalna 100%

Ważna do 26.02.2022

Dobrze
JavaSpringSpring Boot

Asseco Poland S.A.

Administrator / Starszy Administrator Systemów IT

medium

Brak widełek

Kontrakt B2BUmowa o pracę

Praca zdalna 100%

Ważna do 26.02.2022

Dobrze
PostgreSQLBash

Nokia

5G Automation Engineer, IODT

medium

Brak widełek

Umowa o pracę

Wrocław

Praca zdalna 100%

Ważna do 13.03.2022

Divante

Senior Vue.js Developer

senior

15 300 - 23 500 PLN

Kontrakt B2BUmowa o pracę

Wrocław

Praca zdalna 100%

Ważna do 13.03.2022

Dobrze
JavaScriptTypeScriptVue.js

T-Mobile Polska S. A.

Frontend Developer

medium

Brak widełek

Kontrakt B2B

Warszawa

Ważna do 26.02.2022

Bardzo dobrze
ReactReduxNode.js

Commerzbank - Centrum Technologii Cyfrowych w Polsce

Business Expert for Risk Applications

medium

Znamy widełki

Umowa o pracę

Łódź

Ważna do 26.02.2022

Dobrze
SQLMS Office
Początkująco
SAS / R / Python

Commerzbank - Centrum Technologii Cyfrowych w Polsce

Business Expert with German for Risk Analytics

medium

Znamy widełki

Umowa o pracę

Łódź

Ważna do 26.02.2022

Dobrze
MS Office
Początkująco
SQL / VBA / PythonQlik Sense / Qlik View / Arcadia