REST API — co to jest i jak działa?

REST API to standard komunikacji między aplikacjami w internecie. Poznaj 6 zasad REST, metody HTTP, kody statusu i jak projektować API według najlepszych praktyk.

Czym jest REST API?

REST API (Representational State Transfer Application Programming Interface) to architektura komunikacji między aplikacjami przez protokół HTTP. Zaproponowana przez Roya Fieldinga w 2000 roku jako styl architektoniczny dla rozproszonych systemów. Dziś REST API to standard budowania backendu aplikacji webowych i mobilnych.

W REST każdy zasób (użytkownik, produkt, zamówienie) ma swój unikalny adres URI. Operacje na zasobach wykonują metody HTTP: GET pobiera dane, POST tworzy, PUT/PATCH aktualizuje, DELETE usuwa. Odpowiedzi najczęściej w formacie JSON.

# Przykłady REST API dla zasobu "users"

GET /api/v1/users # lista użytkowników

POST /api/v1/users # utwórz użytkownika

GET /api/v1/users/123 # pobierz użytkownika #123

PUT /api/v1/users/123 # zastąp użytkownika #123

PATCH /api/v1/users/123 # zaktualizuj pola użytkownika #123

DELETE /api/v1/users/123 # usuń użytkownika #123

Metody HTTP w REST API

Metoda	Opis	Body	Idempotent	Bezpieczna	Przykład
GET	Pobiera zasób lub listę zasobów	Nie	Tak	Tak	GET /users/123
POST	Tworzy nowy zasób	Tak	Nie	Nie	POST /users
PUT	Zastępuje zasób w całości	Tak	Tak	Nie	PUT /users/123
PATCH	Częściowo aktualizuje zasób	Tak	Nie*	Nie	PATCH /users/123
DELETE	Usuwa zasób	Opcjonalnie	Tak	Nie	DELETE /users/123
HEAD	Jak GET, ale bez ciała odpowiedzi	Nie	Tak	Tak	HEAD /users/123
OPTIONS	Zwraca obsługiwane metody HTTP	Nie	Tak	Tak	OPTIONS /users

* PATCH nie jest z definicji idempotentny, ale może być jeśli operacja jest zdefiniowana idempotentnie

Kluczowe zasady REST API

Stateless (bezstanowość)

Serwer nie przechowuje stanu klienta między żądaniami. Każde żądanie musi zawierać wszystkie potrzebne informacje (token, parametry).

Korzyść:

Skalowalność — dowolny serwer może obsłużyć dowolne żądanie

Przykład:

Zamiast sesji po stronie serwera: Authorization: Bearer <jwt_token> w każdym żądaniu

Uniform Interface

Jednolity interfejs przez cały system: zasoby identyfikowane URI, operacje przez metody HTTP, reprezentacje (JSON/XML), HATEOAS.

Korzyść:

Przewidywalność — developer wiedząc API jednego endpointu, wie jak działają inne

Przykład:

GET /products, POST /products, GET /products/{id}, DELETE /products/{id}

Resource-Based

API operuje na zasobach (rzeczownikach), nie akcjach (czasownikach). Zasób = entity reprezentowana w systemie.

Korzyść:

Intuicyjny design — URL opisuje CO, metoda HTTP opisuje CO ZROBIĆ

Przykład:

Dobrze: DELETE /orders/456. Źle: POST /cancelOrder?id=456

Cacheable

Odpowiedzi muszą oznaczać czy są cacheable. Klienty mogą buforować odpowiedzi GET/HEAD na podstawie nagłówków Cache-Control, ETag.

Korzyść:

Wydajność — mniej żądań do serwera, szybszy czas odpowiedzi

Przykład:

Cache-Control: max-age=3600, ETag: "abc123" + 304 Not Modified

Kody statusu HTTP — REST API

2xx — Sukces

200 OK

Żądanie GET/PUT/PATCH powiodło się

201 Created

POST — zasób został utworzony. Location header z URI nowego zasobu

204 No Content

DELETE lub PUT bez treści odpowiedzi

206 Partial Content

Paginacja, pobieranie fragmentów dużych zasobów (Range)

4xx — Błędy klienta

400 Bad Request

Nieprawidłowe dane wejściowe, błąd walidacji

401 Unauthorized

Brak lub nieprawidłowy token uwierzytelnienia

403 Forbidden

Uwierzytelniony, ale brak uprawnień do zasobu

404 Not Found

Zasób o podanym ID nie istnieje

422 Unprocessable Entity

Dane poprawne składniowo, ale niespełniające logiki biznesowej

429 Too Many Requests

Rate limit przekroczony — Retry-After header

5xx — Błędy serwera

500 Internal Server Error

Nieoczekiwany błąd serwera — logować, nie ujawniać szczegółów

502 Bad Gateway

Upstream serwer zwrócił nieprawidłową odpowiedź

503 Service Unavailable

Serwer tymczasowo niedostępny (maintenance, przeciążenie)

Best practices projektowania REST API

Używaj rzeczowników w URL

Dobrze:

GET /articles, POST /articles, GET /articles/{id}

Unikaj:

GET /getArticles, POST /createArticle

Wersjonuj API od początku

Dobrze:

/api/v1/users, /api/v2/users (breaking changes)

Unikaj:

/api/users (brak wersji = problemy przy zmianach)

Paginacja dla list

Dobrze:

?page=2&per_page=20 lub cursor-based: ?after=xyz123

Unikaj:

Zwracanie wszystkich rekordów bez limitu

Spójne formaty błędów

Dobrze:

{ "error": "validation_failed", "message": "Email is invalid", "field": "email" }

Unikaj:

{ "msg": "err" } lub różne formaty na różnych endpointach

Użyj HTTP semantycznie

Dobrze:

201 Created po POST z Location header, 204 po DELETE

Unikaj:

200 OK dla wszystkich odpowiedzi z błędem w body

FAQ — REST API

Co to jest REST API?

REST API (Representational State Transfer Application Programming Interface) to styl architektoniczny dla rozproszonych systemów hipermedialnych, zaproponowany przez Roya Fieldinga w 2000 roku. REST API używa protokołu HTTP do komunikacji między klientem a serwerem, gdzie zasoby są identyfikowane przez URI (np. /users/123), a operacje na nich wykonują standardowe metody HTTP: GET (odczyt), POST (tworzenie), PUT/PATCH (aktualizacja), DELETE (usuwanie).

Jakie są zasady REST API?

6 zasad REST (constraints): 1) Client-Server — rozdzielenie klienta od serwera, 2) Stateless — każde żądanie zawiera wszystkie potrzebne informacje (brak sesji po stronie serwera), 3) Cacheable — odpowiedzi mogą być buforowane, 4) Uniform Interface — jednolity interfejs (URI, metody HTTP, reprezentacje), 5) Layered System — architektura warstwowa (load balancery, cache, security), 6) Code on Demand (opcjonalne) — serwer może przesyłać kod wykonywalny.

Czym różni się REST od SOAP?

REST używa lekkich formatów (JSON, XML) i standardowych metod HTTP — jest prostszy, szybszy i bardziej popularny w nowoczesnych aplikacjach. SOAP (Simple Object Access Protocol) to protokół z własnym formatem XML, obsługuje zaawansowane standardy bezpieczeństwa (WS-Security), transakcje i niezawodność — używany w bankowości, telekomunikacji i enterprise. REST jest bezstanowy i stateless, SOAP może być stateful.

Co to są kody statusu HTTP w REST API?

Kody statusu HTTP komunikują wynik żądania: 2xx (sukces) — 200 OK, 201 Created, 204 No Content; 3xx (przekierowania) — 301 Moved Permanently, 304 Not Modified; 4xx (błędy klienta) — 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity, 429 Too Many Requests; 5xx (błędy serwera) — 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable.

Jak zabezpieczyć REST API?

Podstawowe metody bezpieczeństwa REST API: HTTPS (szyfrowanie transportu), JWT (JSON Web Token) lub OAuth 2.0 do uwierzytelniania, API Keys do identyfikacji aplikacji, Rate limiting (ograniczenie liczby żądań), Input validation (walidacja danych wejściowych), CORS (Cross-Origin Resource Sharing), versioning (/api/v1/), oraz monitoring anomalii. Nigdy nie przechowuj danych wrażliwych w URL.

Czytaj dalej