REST API

REST API (ang. Representational State Transfer Application Programming Interface) to interfejs programistyczny aplikacji oparty na zasadach architektury REST. Umożliwia komunikację między systemami za pośrednictwem protokołu HTTP, wykorzystując standardowe metody tego protokołu oraz formaty wymiany danych, takie jak JSON i XML.

Historia i kontekst

Koncept REST został sformułowany w 2000 roku przez Roye Fieldinga w jego rozprawie doktorskiej. Idea ta wyrosła z potrzeby uproszczenia usług sieciowych i odróżnienia ich od bardziej złożonych rozwiązań opartych na architekturze zorientowanej na usługi (SOA). Pierwsze publiczne REST API pojawiły się w połowie pierwszej dekady XXI wieku, m.in. w serwisach takich jak Twitter czy Flickr.

Podstawowe zasady REST

Jednolitość interfejsu – wszystkie zasoby są identyfikowane przy pomocy URI i manipulowane przy użyciu standardowych metod HTTP (GET, POST, PUT, DELETE, PATCH).
Bezustatność – każde żądanie od klienta musi zawierać pełną informację niezbędną do jego obsługi; serwer nie utrzymuje stanu sesji po stronie.
Cache’owalność – odpowiedzi mogą być buforowane, co zwiększa wydajność i zmniejsza obciążenie sieci.
Warstwa systemowa – architektura może być podzielona na warstwy, z których każda jest odseparowana od pozostałych.
Hipermedia jako silnik aplikacji (HATEOAS) – odpowiedzi zawierają odnośniki (hypermedia links) umożliwiające dynamiczne odkrywanie dostępnych działań.

Budowa i elementy REST API

Typowy REST API składa się z następujących elementów:

Zasoby – abstrakcyjne byty reprezentowane w systemie (np. użytkownicy, produkty). Każdy zasób ma unikalny identyfikator URI, np. /users/123.
Metody HTTP – określają operacje na zasobach:
- GET – pobranie reprezentacji zasobu.
- POST – utworzenie nowego zasobu.
- PUT – pełna aktualizacja istniejącego zasobu.
- PATCH – częściowa aktualizacja.
- DELETE – usunięcie zasobu.
Formaty reprezentacji – najczęściej używane to JSON oraz XML. Wybór formatu zależy od potrzeb aplikacji oraz wymagań interoperacyjnych.
Kody statusu HTTP – informują o wyniku operacji (np. 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error).
Autoryzacja i uwierzytelnianie – popularne mechanizmy to OAuth, JSON Web Token (JWT) oraz podstawowe uwierzytelnianie (Basic Auth).

Zalety REST API

Prostota i czytelność – opiera się na powszechnie znanym protokole HTTP.
Skalowalność – dzięki bezstanowości i możliwości buforowania.
Łatwa integracja – wiele języków programowania oferuje biblioteki do obsługi JSON i XML.
Elastyczność – możliwość rozwijania interfejsu bez zmiany istniejących klientów (zgodność wsteczna).

Ograniczenia i wyzwania

Brak standaryzacji hipermedialnych linków – implementacje HATEOAS mogą się różnić.
Ograniczona kontrola transakcji – brak natywnego wsparcia dla operacji atomowych (w przeciwieństwie do np. SOAP).
Konieczność dbałości o bezpieczeństwo – otwarte endpointy API są potencjalnym wektorem ataków.

Przykładowe zastosowania

REST API jest wykorzystywane w:

aplikacjach mobilnych – umożliwia pobieranie danych z serwera w czasie rzeczywistym,
systemach integracji biznesowej – łączenie systemów ERP z portalami e‑commerce,
platformach chmurowych – oferowanie usług jako SaaS,
aplikacjach IoT – wymiana danych pomiędzy urządzeniami a serwerem centralnym.

Porównanie z innymi stylami architektonicznymi

Cecha	REST	SOAP	GraphQL
Protokół transportowy	HTTP	HTTP, SMTP, JMS	HTTP
Format wiadomości	JSON, XML, inne	XML (SOAP envelope)	JSON
Stanowość	Bezustatny	Możliwy stan (wsparcie sesji)	Bezustatny
Obsługa hipermediów	Tak (HATEOAS)	Nie (wszystko w ciele SOAP)	Nie bezpośrednio

Standardy i specyfikacje powiązane

RFC 7230‑7235 – definiują standardy HTTP/1.1.
OpenAPI (Swagger) – format opisu REST API, umożliwiający automatyczną generację dokumentacji i kodu klienckiego.
JSON:API – specyfikacja standardizująca struktury odpowiedzi JSON.
HAL (Hypertext Application Language) – konwencja formatowania hipermedialnych linków w odpowiedziach JSON.

Przykład prostego zapytania

GET /api/v1/users/42 HTTP/1.1
Host: api.przyklad.com
Accept: application/json

Odpowiedź serwera:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 42,
    "name": "Jan Kowalski",
    "email": "jan.kowalski@example.com",
    "_links": {
        "self": { "href": "/api/v1/users/42" },
        "orders": { "href": "/api/v1/users/42/orders" }
    }
}

Przyszłość REST API

Mimo rosnącej popularności alternatywnych podejść, takich jak GraphQL czy gRPC, REST pozostaje dominującym stylem wymiany danych w Internecie. Rozwój standardów takich jak OpenAPI oraz technik zabezpieczania (np. OAuth 2.0) zapewnia, że architektura ta będzie wspierać nowoczesne aplikacje przez kolejne lata.