Frontend wyświetla listę produktów, ale każde kliknięcie kończy się osobnym, niespójnym żądaniem do serwera. REST API zwykle porządkuje taką komunikację wokół zasobów i standardowych metod HTTP, choć samo użycie adresów URL i JSON nie wystarcza, by interfejs był naprawdę RESTful.

Dobre API pozwala przewidzieć, co zrobi każde żądanie
- Zasób opisuje rzecz lub obiekt, na przykład produkt albo zamówienie.
- Metoda HTTP określa działanie, a nie czasownik dopisany do adresu.
- Bezstanowość oznacza, że każde żądanie niesie dane potrzebne do jego obsługi.
- Ponowienie żądania jest bezpieczniejsze dla operacji idempotentnych, takich jak PUT.
- Błędy powinny korzystać z kodów HTTP i spójnego formatu odpowiedzi.
REST API porządkuje interfejs wokół zasobów, nie ekranów
Wyobraź sobie sklep, w którym frontend potrzebuje pobrać szczegóły zamówienia. W interfejsie opartym na zasobach żądanie może wyglądać tak: GET /orders/583. Adres wskazuje zamówienie, metoda mówi, że chodzi o odczyt, a odpowiedź zawiera jego reprezentację, na przykład w JSON.
Ta różnica szybko wychodzi na jaw przy rozbudowie serwisu. Endpointy w rodzaju /getOrder, /createOrder i /cancelOrder opisują konkretne polecenia; ścieżki /orders oraz /orders/583 wskazują zasoby, z którymi można pracować za pomocą metod HTTP. Adres nazywa rzecz, metoda określa operację.
REST oznacza Representational State Transfer. W pracy Roya Fieldinga architektura ta opiera się między innymi na bezstanowej komunikacji, jednolitym interfejsie oraz możliwości korzystania z pamięci podręcznej. Rozprawa Roya Fieldinga opisuje też hipermedia jako sposób prowadzenia klienta przez dostępne działania. Wiele popularnych interfejsów nazywanych REST API wykorzystuje część tych zasad, ale nie wszystkie.
JSON i HTTP same nie czynią interfejsu RESTful
Tu kryje się częsta pułapka: można przesyłać JSON przez HTTP i nadal projektować interfejs jak zestaw zdalnych funkcji. Przykładowo POST /getUserById może działać poprawnie, ale używa adresu jak nazwy procedury, zamiast wskazać zasób użytkownika.
JSON to format danych, HTTP to protokół komunikacji, a REST to styl architektury. Nie należy utożsamiać tych pojęć. W pełniejszym podejściu klient może korzystać z odnośników zwracanych przez serwer, zamiast zakładać na stałe każdy kolejny adres; w praktyce wiele API tego nie robi, dlatego określenie „RESTful” bywa stosowane do interfejsów o różnym stopniu zgodności z założeniami REST.
Nie traktowałbym tej różnicy jak testu czystości projektu. Dla aplikacji ważniejszy jest przewidywalny kontrakt: jasne adresy, semantyczne metody, sensowne kody odpowiedzi i dokumentacja. Ścisłe HATEOAS, czyli sterowanie przepływem przez odnośniki w odpowiedziach, może być przydatne w otwartym, ewoluującym API, ale dokłada pracy klientom i zespołowi.
Dobór metody HTTP wpływa na ponawianie żądań
Gdy połączenie urwie się tuż po wysłaniu żądania, klient może nie wiedzieć, czy serwer wykonał operację. Dlatego znaczenie ma idempotencja: ponowne wysłanie identycznego żądania daje ten sam zamierzony skutek, co wysłanie go raz. RFC 9110 zalicza do metod idempotentnych między innymi PUT i DELETE, ale nie POST.
Przykład: aktualizacja adresu dostawy przez PUT /orders/583 może zostać ponowiona po błędzie sieci bez tworzenia drugiego zamówienia. Gdy klient ponawia POST /orders, może powstać duplikat. Jeśli operacja tworzenia musi być odporna na ponowienia, trzeba zaprojektować dodatkowy mechanizm, na przykład klucz idempotencji, i określić, jak długo serwer pamięta jego użycie.
| Sytuacja | Możliwa przyczyna lub skutek | Co zrobić |
|---|---|---|
| Połączenie przerwało się po POST tworzącym zamówienie | Nie wiadomo, czy serwer zdążył utworzyć rekord; ponowienie może dodać drugi | Sprawdź wynik po identyfikatorze albo użyj uzgodnionego klucza idempotencji |
| PUT nadpisuje zasób innymi danymi przy każdym powtórzeniu | Żądanie nie zachowuje się zgodnie z oczekiwaną idempotencją | Sprawdź semantykę endpointu i oddziel pełną aktualizację od operacji powodującej skutek uboczny |
| PATCH zmienia tylko podane pola | Skutek zależy od tego, czy aktualizacja jest zapisana jako powtarzalna | Ustal format PATCH i opisz zachowanie przy ponowieniu |
| GET zmienia stan, na przykład nalicza opłatę | Klient, cache lub robot może wywołać operację w nieoczekiwanym momencie | Przenieś zmianę stanu do metody przeznaczonej do takiej operacji |
Praktyczna reguła: jeśli żądanie ma dać się automatycznie ponawiać po niepewnym błędzie sieci, zaprojektuj je jako idempotentne albo dodaj mechanizm, który zapobiega powtórnemu wykonaniu. Sam wybór metody nie naprawi niejasnej logiki biznesowej.
Spójne błędy oszczędzają czas przy integracji
Odpowiedź z kodem 200 i komunikatem „wystąpił błąd” zmusza klienta do zgadywania, czy operacja się udała. Kod HTTP powinien odzwierciedlać wynik, a treść odpowiedzi dopowiadać, co poszło nie tak i jak odczytać problem.
Do ujednolicania błędów HTTP służy format Problem Details zdefiniowany w RFC 9457. Może zawierać typ problemu, tytuł, status i szczegóły, które pomagają klientowi zareagować. Nie powinien jednak ujawniać sekretów, fragmentów zapytań ani danych wewnętrznych serwera.
W typowym sklepie błąd walidacji danych zamówienia powinien wskazywać, które pole wymaga poprawy, a brak wskazanego zamówienia powinien być odróżniony od awarii serwera. Spójny kształt błędu pozwala frontendowi pokazać użyteczny komunikat bez pisania osobnej obsługi dla każdego endpointu.
REST sprawdza się przy przewidywalnych zasobach, a nie każdej operacji
Lista produktów, profil klienta czy zamówienia dobrze pasują do modelu zasobów: można je pobierać, tworzyć, aktualizować i usuwać. Trudniej dopasować do niego działania takie jak „wyślij ponownie kod”, „przelicz ofertę” czy „zatwierdź płatność”, bo są poleceniami biznesowymi, a nie prostym odczytem lub zapisem obiektu.
W takim przypadku da się użyć dodatkowej ścieżki opisującej działanie albo rozważyć styl RPC, w którym API eksponuje wywoływane operacje. Jeśli większość interfejsu obraca się wokół zasobów, zacznij od REST; jeśli kontrakt składa się głównie z poleceń i złożonych przepływów, nie wciskaj każdego z nich w pozornie REST-owy adres. Uważam, że czytelny kontrakt jest lepszy od zgodności osiąganej wyłącznie kosmetyczną zmianą nazw.
Wybór zależy też od klientów. Publiczne API dla wielu niezależnych aplikacji korzysta z powszechnego wsparcia HTTP i łatwo daje się testować zwykłymi narzędziami. W komunikacji między usługami o wspólnym kontrakcie można rozważyć RPC lub gRPC, zwłaszcza gdy potrzebne są silnie typowane wiadomości albo komunikacja strumieniowa; to jednak inny zestaw kompromisów, a nie automatyczna poprawa każdego API.
Dobre API zaczyna się od kontraktu, który da się przewidzieć
Najprostszy test projektu brzmi: czy osoba integrująca frontend potrafi przewidzieć adres, metodę, odpowiedź i błąd bez poznawania wnętrza backendu? Jeśli tak, interfejs jest czytelny. Jeśli każda operacja wymaga osobnej konwencji, problem zwykle leży w kontrakcie, nie w braku kolejnej biblioteki.
Zacznij od modelu zasobów, dobierz metody zgodnie z ich semantyką, a błędy i ponowienia opisz równie starannie jak odpowiedzi sukcesu. Wtedy komunikacja między ekranem a serwerem przestaje przypominać zbiór wyjątków i zaczyna być przewidywalną częścią produktu.