REST API — czym jest i jak działa

REST API to popularny sposób projektowania webowego API wokół zasobów, takich jak użytkownicy, zadania czy zamówienia. Każdy zasób ma własny URL, a metody HTTP, takie jak GET, POST, PATCH i DELETE, mówią serwerowi, co klient chce zrobić.

REST oznacza Representational State Transfer. W praktyce klient wysyła żądanie HTTP, serwer zwraca reprezentację zasobu, a każde żądanie powinno mieć sens samo w sobie. Wiele REST API zwraca JSON, ale sam JSON nie sprawia jeszcze, że API jest zgodne z REST.

Znaczenie REST API: myśl zasobami

Najszybszy sposób, by zrozumieć REST, to myśleć rzeczownikami, a nie czasownikami.

Jeśli twój system ma zadania, uczniów i próby, to właśnie one mogą być zasobami. API zorientowane na zasoby zwykle używa URL-i takich jak /api/problems/42 albo /api/attempts/9001.

Metoda HTTP mówi wtedy, jaki rodzaj operacji się odbywa:

• GET odczytuje zasób
• POST tworzy nowy zasób
• PUT zastępuje zasób
• PATCH aktualizuje część zasobu
• DELETE usuwa zasób

To rozdzielenie sprawia, że REST łatwo się analizuje. URL mówi, na czym pracujesz. Metoda mówi, co chcesz zrobić.

Jak działa żądanie w REST API

W typowym przepływie przeglądarka, aplikacja mobilna albo inna usługa wysyła żądanie do serwera. Żądanie zawiera URL, metodę HTTP, opcjonalne nagłówki, a czasem także body.

Serwer odczytuje żądanie, wykonuje działanie i zwraca odpowiedź. Taka odpowiedź zwykle zawiera kod statusu, taki jak 200 OK, 201 Created albo 404 Not Found, oraz dane opisujące wynik.

Jednym z ważnych warunków jest bezstanowość. W REST każde żądanie powinno zawierać kontekst potrzebny do jego obsługi. Nie oznacza to, że serwer nie przechowuje żadnych danych. Oznacza to, że serwer nie powinien potrzebować ukrytego stanu rozmowy z wcześniejszych żądań, aby zrozumieć bieżące.

Przykład REST API: aplikacja do ćwiczenia matematyki

Załóżmy, że aplikacja do ćwiczenia matematyki przechowuje zadania z algebry i próby uczniów.

Aby odczytać zadanie $42$, klient może wysłać: