REST API: co to jest, metody HTTP i zasada działania w aplikacjach mobilnych

Co to jest REST API?

REST API (Representational State Transfer API) — to architektoniczny styl zaproponowany przez Roya Fieldinga w jego rozprawie doktorskiej w 2000 roku. Określa on zestaw ograniczeń i zasad projektowania protokołów sieciowych. API zgodny z tymi ograniczeniami nazywany jest RESTful. REST nie jest protokołem ani standardem — to podejście architektoniczne, które używa istniejących protokołów (głównie HTTP) do wymiany danych między klientem a serwerem.

Kluczową ideą REST jest architektura zorientowana na zasoby. Zamiast wywoływania metod na serwerze (jak w SOAP lub RPC), klient operuje na zasobach: pobiera ich listę, tworzy nowe, aktualizuje lub usuwa. Każdy zasób to encja dziedziny: użytkownik, zamówienie, produkt, artykuł. Zasób ma stan, który jest przesyłany klientowi w standaryzowanym formacie, zazwyczaj JSON. Serwer nie przechowuje stanu klienta między zapytaniami — to zasada stateless, kluczowe wymaganie REST.

Główne cechy REST API:

• Stateless — każde zapytanie od klienta zawiera wszystkie informacje potrzebne do jego przetworzenia
• Cacheable — odpowiedzi serwera muszą być jawnie oznaczone jako buforowalne lub niebuforowalne
• Layered system — architektura może zawierać serwery pośrednie, load balancery, proxy
• Uniform interface — jednolity interfejs interakcji poprzez metody HTTP, URL i kody statusu

Zasady architektury REST

REST opiera się na sześciu ograniczeniach architektonicznych sformułowanych przez Fieldinga. Przestrzeganie tych ograniczeń gwarantuje skalowalność, wydajność i łatwość integracji. Każda zasada rozwiązuje konkretny problem systemów rozproszonych — od potrzeby buforowania po wymagania bezpieczeństwa. Przyjrzyjmy się każdej zasadzie szczegółowo.

Zasada Uniform Interface dodatkowo obejmuje cztery pod-ograniczenia: identyfikację zasobów przez URI, manipulację zasobami przez reprezentacje, samoopisujące się komunikaty i HATEOAS (hipermedia jako silnik stanu aplikacji). To ostatnie pod-ograniczenie jest często ignorowane w praktyce — większość nowoczesnych REST API nie implementuje w pełni HATEOAS, co prowadzi do dyskusji, czy takie API jest „prawdziwym” RESTful.

Zasada Stateless — jedna z najważniejszych dla skalowania. Brak sesji na serwerze oznacza, że dowolna instancja serwera może obsłużyć dowolne zapytanie. To upraszcza skalowanie poziome: wystarczy dodać nowe serwery za load balancerem. Dla aplikacji mobilnych stateless oznacza również, że zapytanie może być wysłane do dowolnego serwera CDN, co jest kluczowe dla globalnej dostępności.

Metody HTTP w REST

Każda metoda HTTP w REST API odpowiada określonej operacji na zasobie: GET do odczytu, POST do tworzenia, PUT do pełnej aktualizacji, PATCH do częściowej aktualizacji, DELETE do usuwania. Idempotentność metod to kluczowa cecha: GET, PUT, DELETE są idempotentne (wielokrotne wykonanie daje ten sam wynik), POST i PATCH — nie. Jest to ważne przy obsłudze błędów sieci, gdy klient nie wie, czy zapytanie dotarło do serwera.

• GET — pobranie zasobu lub listy zasobów. Idempotentny, nie zmienia stanu serwera
• POST — tworzenie nowego zasobu. Nieidempotentny, każde wywołanie tworzy nowy zasób
• PUT — pełna zamiana zasobu. Idempotentny, ponowne wywołanie nie zmienia stanu po pierwszym
• PATCH — częściowa aktualizacja zasobu. Częściowo idempotentny (zależy od implementacji)
• DELETE — usunięcie zasobu. Idempotentny, ponowne usunięcie zwraca 404, a nie błąd

Kody statusu HTTP są nieodłączną częścią REST API. Każdy kod niesie określone znaczenie: 200 OK dla udanego GET, 201 Created dla POST, 204 No Content dla DELETE bez treści odpowiedzi, 400 Bad Request przy nieprawidłowych danych, 401 Unauthorized przy braku autoryzacji, 404 Not Found przy braku zasobu. Prawidłowe używanie kodów statusu czyni API samodokumentującym się i upraszcza debugowanie.

Formaty danych: JSON i inne

JSON (JavaScript Object Notation) — główny format przesyłania danych w REST API. Jego popularność wynika z prostoty, czytelności i natywnej obsługi w JavaScript. JSON przesyłany jest z nagłówkiem Content-Type: application/json. Alternatywy obejmują XML (rozbudowany, wycofywany), YAML (wygodny do konfiguracji, rzadziej dla API) i Protocol Buffers (binarny, wydajny dla systemów o dużym obciążeniu).

Struktura obiektu JSON w REST API zwykle zawiera pola id, type i atrybuty zasobu. Dla kolekcji używany jest JSON-array z metadanymi paginacji. Nowoczesne REST API stosują się do specyfikacji JSON:API (jsonapi.org) lub JSON Schema do walidacji odpowiedzi. Użycie jednolitego formatu danych upraszcza tworzenie bibliotek klienckich i generowanie dokumentacji.

Przykład odpowiedzi JSON dla listy użytkowników:

{
    "data": [
        {
            "id": 1,
            "name": "Anna Pietrowa",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

Wybór formatu przesyłania danych wpływa na wydajność aplikacji mobilnej. JSON kompresuje się przez GZIP o 70–80%, co czyni go akceptowalnym dla większości scenariuszy. Dla aplikacji czasu rzeczywistego z dużą ilością danych (streaming, gry) zaleca się przejść na protokoły binarne lub użyć WebSocket w kombinacji z Protocol Buffers.

Przykłady zapytań REST API

Rozważmy praktyczne przykłady pracy z REST API po stronie aplikacji mobilnej. Jako przykład weźmiemy API do pracy z zamówieniami w sklepie internetowym. Dla każdej metody HTTP pokazane jest zapytanie i oczekiwana odpowiedź serwera. Przykłady demonstrują typową strukturę RESTful API stosowaną w tworzeniu aplikacji mobilnych.

GET — pobranie listy zamówień

Zapytanie o pobranie wszystkich zamówień użytkownika z paginacją. Odpowiedź zawiera tablicę obiektów zamówień i metainformacje do nawigacji stronicowej. Parametry page i per_page przekazywane są przez query string.

// Interfejs Retrofit dla REST API
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — tworzenie nowego zamówienia

Tworzenie nowego zamówienia przez zapytanie POST. Serwer zwraca status 201 Created i utworzony obiekt w treści odpowiedzi. Ważne: tworzenie odbywa się na kolekcji /api/v1/orders, a nie na konkretnym zasobie — to standardowy wzorzec RESTful.

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// Przykład treści żądania
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — usunięcie zamówienia

Usunięcie zasobu wykonuje się metodą DELETE pod konkretnym URL zamówienia. Pomyślne usunięcie zwraca 204 No Content. Idempotentność DELETE oznacza, że ponowne zapytanie pod ten sam URL zwróci 404 Not Found, co jest poprawnie obsługiwane po stronie klienta.

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// Użycie w ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Te przykłady demonstrują typową implementację REST API po stronie Androida z użyciem Retrofit i Kotlin Coroutines. Dla aplikacji iOS analogiczną rolę pełni URLSession lub biblioteka Alamofire w połączeniu z protokołami Codable. Struktura REST API pozostaje taka sama niezależnie od platformy — zmienia się tylko sposób wykonywania zapytań.

Projektowanie RESTful API: praktyczne zalecenia

Projektowanie wysokiej jakości RESTful API wymaga przestrzegania konwencji, które czynią API intuicyjnym dla programistów. Zasoby powinny być nazwane rzeczownikami w liczbie mnogiej (/users, /orders, /products), metody HTTP odzwierciedlać operacje, a URL — hierarchię zagnieżdżenia. Błędy powinny zwracać standaryzowany JSON z kodem i komunikatem, a nie tylko status HTTP. Przestrzeganie tych konwencji obniża próg wejścia dla nowych programistów i upraszcza integrację.

• Nazewnictwo zasobów — liczba mnoga, kebab-case: /api/v1/user-orders, nie /api/v1/getUserOrders
• Filtrowanie i sortowanie — przez parametry query: ?status=active&sort=created_at:desc
• Paginacja — cursor-based dla dużych zbiorów, page-based dla małych
• Wersjonowanie — przez URL (/api/v2/) lub nagłówek Accept-Version
• Błędy — jednolity format: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — nagłówki X-RateLimit-Remaining i Retry-After

Jednym z częstych błędów przy projektowaniu REST API jest nadmierne zagnieżdżenie zasobów. Zamiast /users/1/orders/5/items/3 lepiej użyć płaskiej struktury z parametrami query: /items?order_id=5&user_id=1. To upraszcza buforowanie, nie wymaga obsługi długich ścieżek na serwerze i jest łatwiejsze do dokumentowania. Płaska architektura jest również lepiej kompatybilna z zapytaniami graph-based przy przejściu na GraphQL w przyszłości.

Bezpieczeństwo REST API realizuje się poprzez uwierzytelnianie (JWT, OAuth 2.0) i autoryzację na poziomie zasobów. Każde zapytanie powinno sprawdzać, czy użytkownik ma dostęp do żądanego zasobu. HTTPS jest obowiązkowe — bez szyfrowania tokeny i dane są przesyłane w otwartej postaci. Dla aplikacji mobilnych zaleca się stosowanie OAuth 2.0 z PKCE (Proof Key for Code Exchange) do bezpiecznego uzyskiwania tokenów.

Wersjonowanie i buforowanie

Wersjonowanie REST API jest niezbędne do zachowania kompatybilności wstecznej przy zmianach. Najczęstsze podejścia: wersja w URL (/api/v1/orders), wersja w nagłówku (Accept: application/vnd.myapi.v1+json) i wersja w parametrze query (?api_version=1). Wersjonowanie przez URL jest najpopularniejszą metodą, ponieważ jest wyraźnie widoczne w logach i dokumentacji. Jednak narusza ono zasadę REST o jednolitym URL zasobu.

Buforowanie w REST API realizuje się przez nagłówki HTTP Cache-Control, ETag i Last-Modified. Zapytania GET oznaczone jako buforowalne mogą być obsługiwane z pamięci podręcznej przeglądarki lub proxy bez odwoływania się do serwera. Dla aplikacji mobilnych buforowanie jest szczególnie ważne — zmniejsza zużycie transmisji danych i przyspiesza wyświetlanie wcześniej załadowanych danych przy słabym połączeniu. ETag to skrót treści odpowiedzi: klient wysyła go w If-None-Match, a serwer zwraca 304 Not Modified, jeśli dane się nie zmieniły.

Nowoczesne alternatywy REST API obejmują GraphQL (elastyczny wybór danych przez klienta) i gRPC (binarny protokół na HTTP/2 dla mikrousług). Jednak REST pozostaje głównym standardem dla publicznych API dzięki swojej prostocie, uniwersalności i szerokiemu wsparciu narzędzi. Wybór między REST a alternatywami zależy od konkretnych wymagań projektu: złożoności zapytań, ilości danych, wymagań dotyczących aktualizacji czasu rzeczywistego.