REST API — co to jest i jak zacząć? Przewodnik z przykładami w curl i Pythonie

REST API to interfejs, przez który aplikacje komunikują się ze sobą za pomocą protokołu HTTP: każdy zasób (np. użytkownik, zamówienie) ma swój adres URL, a operacje na nim wykonujesz standardowymi metodami GET, POST, PUT, PATCH i DELETE. Serwer odpowiada kodem statusu i danymi — dziś niemal zawsze w formacie JSON.

Z REST API korzystasz codziennie, nawet o tym nie wiedząc: aplikacja pogodowa pobiera prognozę, sklep internetowy sprawdza status płatności, a aplikacja mobilna banku pokazuje saldo. Poniżej wyjaśniam, jak to działa, i pokazuję, jak samodzielnie wysłać pierwsze zapytania oraz postawić własne, małe API.

REST API — co to jest i skąd się wzięło

REST (Representational State Transfer) to styl architektury systemów rozproszonych opisany przez Roya Fieldinga w jego rozprawie doktorskiej z 2000 roku. Fielding był jednym z autorów specyfikacji HTTP, więc REST od początku był „skrojony” pod sieć WWW.

API (Application Programming Interface) to po prostu umowa: jakie zapytania możesz wysłać i jakie odpowiedzi dostaniesz. REST API to więc API webowe zbudowane według zasad REST.

Ważne rozróżnienie: REST nie jest protokołem ani standardem jak SOAP. Nie ma oficjalnej specyfikacji „REST API”, którą można zwalidować. Dlatego w praktyce spotkasz API w pełni zgodne z zasadami Fieldinga, ale też takie, które nazywają się RESTowe, a są po prostu „JSON przez HTTP”.

Sześć zasad architektury REST

Fielding zdefiniował zestaw ograniczeń (constraints). API, które je spełnia, jest RESTful.

1. Klient–serwer — interfejs użytkownika jest oddzielony od przechowywania danych. Aplikacja mobilna i strona WWW mogą korzystać z tego samego API.
2. Bezstanowość — każde zapytanie zawiera wszystko, czego serwer potrzebuje do jego obsłużenia (np. token uwierzytelniający). Serwer nie pamięta „sesji” klienta między zapytaniami, dzięki czemu łatwo dołożyć kolejne serwery za load balancerem.
3. Cache’owalność — odpowiedź musi określać, czy można ją przechowywać w pamięci podręcznej (nagłówki Cache-Control, ETag). To odciąża serwer.
4. Jednolity interfejs — zasoby identyfikowane są adresami URI, operuje się na nich za pomocą reprezentacji (np. JSON), a komunikaty są samoopisowe (metoda, nagłówki, kod statusu).
5. System warstwowy — między klientem a serwerem mogą stać proxy, CDN czy bramka API, a klient nie musi o nich wiedzieć.
6. Kod na żądanie (opcjonalnie) — serwer może przesłać klientowi kod do wykonania, np. skrypt JavaScript.

Część jednolitego interfejsu stanowi też HATEOAS — odpowiedź zawiera linki do powiązanych akcji i zasobów. W praktyce mało które publiczne API wdraża to w pełni, ale warto znać to pojęcie, bo pojawia się na rozmowach rekrutacyjnych.

Zasoby i adresy URL: jak wygląda endpoint

W REST myślisz rzeczownikami, nie czasownikami. Zasobem jest „użytkownik”, a nie „pobierzUżytkownika”. Typowa struktura adresów:

GET    /api/v1/users            → lista użytkowników
GET    /api/v1/users/42         → użytkownik o id 42
POST   /api/v1/users            → utworzenie użytkownika
PATCH  /api/v1/users/42         → zmiana wybranych pól
DELETE /api/v1/users/42         → usunięcie
GET    /api/v1/users/42/orders  → zamówienia użytkownika 42
GET    /api/v1/orders?status=paid&page=2&limit=20  → filtrowanie i stronicowanie

Dobre praktyki, które ułatwią życie Tobie i użytkownikom API:

• nazwy zasobów w liczbie mnogiej i małymi literami (/users, /orders),
• filtrowanie, sortowanie i stronicowanie w parametrach zapytania, a nie w ścieżce,
• wersja API w ścieżce (/v1/) lub nagłówku — pozwala zmieniać API bez psucia starych klientów,
• zagnieżdżanie najwyżej na jeden poziom (/users/42/orders, ale już nie /users/42/orders/7/items/3/...).

Metody HTTP w REST API

Metoda mówi serwerowi, co chcesz zrobić z zasobem. Dwie cechy są tu istotne: metoda bezpieczna nie zmienia stanu serwera, a idempotentna daje ten sam efekt bez względu na to, ile razy ją powtórzysz.

Idempotentność ma praktyczne znaczenie: jeśli połączenie zerwie się w trakcie PUT, klient może bezpiecznie ponowić zapytanie. Powtórzony POST może natomiast utworzyć duplikat — np. drugie zamówienie. Dlatego API płatności często wymagają nagłówka typu Idempotency-Key.

Kody odpowiedzi HTTP, które musisz znać

Kod statusu to pierwsza rzecz, którą sprawdza klient. Najczęściej spotykane:

Treść błędu warto zwracać w przewidywalnym formacie. Standardem jest „Problem Details” z RFC 9457 (application/problem+json) z polami type, title, status i detail.

Jak zacząć: pierwsze zapytania do REST API w curl

Najszybciej zrozumiesz REST, wysyłając prawdziwe zapytania. Dobrym poligonem jest publiczne testowe API JSONPlaceholder, które udaje serwis z postami i użytkownikami. Narzędzie curl jest wbudowane w Linuxa, macOS i Windows 10/11.

1. Pobierz jeden zasób (GET):

curl -i https://jsonplaceholder.typicode.com/posts/1

Przełącznik -i pokazuje nagłówki odpowiedzi — zobaczysz HTTP/2 200 i content-type: application/json.

2. Pobierz listę z filtrem w parametrze zapytania:

curl "https://jsonplaceholder.typicode.com/posts?userId=1"

3. Utwórz zasób (POST z danymi JSON):

curl -i -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "Mój pierwszy post", "body": "Treść", "userId": 1}'

Serwer odpowie kodem 201 Created i zwróci obiekt z nadanym id. To API tylko symuluje zapis, więc dane nie zostaną trwale dodane.

4. Sprawdź błąd — zapytaj o nieistniejący zasób:

curl -i https://jsonplaceholder.typicode.com/posts/99999

Dostaniesz 404 Not Found. Tak samo będzie się zachowywać każde dobrze zaprojektowane API.

Wskazówka: W PowerShellu curl bywa aliasem Invoke-WebRequest (w Windows PowerShell 5.1). Wpisz curl.exe, żeby mieć pewność, że uruchamiasz prawdziwy curl, albo użyj Invoke-RestMethod, który od razu zamienia JSON na obiekty.

Jeśli wolisz interfejs graficzny, te same zapytania wyślesz w Postmanie, Insomni, Bruno albo rozszerzeniu REST Client w VS Code. W przeglądarce samo wejście na adres to zapytanie GET, a zakładka „Sieć” w narzędziach deweloperskich (F12) pokazuje, z jakich API korzysta dana strona.

Uwierzytelnianie w REST API

Ponieważ REST jest bezstanowy, każde zapytanie musi samo udowodnić, kto je wysyła. Najpopularniejsze metody:

• Klucz API — stały ciąg w nagłówku (np. X-API-Key) lub parametrze. Prosty, typowy dla publicznych usług, np. Google Maps API.
• Bearer token — nagłówek Authorization: Bearer <token>, często w formacie JWT, wydawany po zalogowaniu.
• OAuth 2.0 — gdy aplikacja działa w imieniu użytkownika innego serwisu („Zaloguj przez Google”).

curl https://api.example.com/v1/me \
  -H "Authorization: Bearer TWOJ_TOKEN"

Uwaga: Nigdy nie umieszczaj kluczy API ani tokenów w kodzie frontendu, publicznym repozytorium czy w adresie URL. Trzymaj je w zmiennych środowiskowych, a w przeglądarce unikaj zapisywania tokenów w Local Storage, jeśli aplikacja jest podatna na XSS.

Gdy API korzysta z ciasteczek sesyjnych zamiast tokenów w nagłówku, musisz dodatkowo zabezpieczyć je przed atakami CSRF.

Własne REST API w 10 minut: przykład w FastAPI

Najlepszy sposób, żeby zrozumieć REST od drugiej strony, to napisać serwer. Poniżej minimalne API w Pythonie z frameworkiem FastAPI (dane trzymane w pamięci, bez bazy).

1. Zainstaluj FastAPI:

pip install "fastapi[standard]"

2. Utwórz plik main.py:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class Task(BaseModel):
    title: str
    done: bool = False

tasks: dict[int, Task] = {}
next_id = 1

@app.get("/tasks")
def list_tasks():
    return [{"id": i, **t.model_dump()} for i, t in tasks.items()]

@app.get("/tasks/{task_id}")
def get_task(task_id: int):
    if task_id not in tasks:
        raise HTTPException(status_code=404, detail="Nie ma takiego zadania")
    return {"id": task_id, **tasks[task_id].model_dump()}

@app.post("/tasks", status_code=201)
def create_task(task: Task):
    global next_id
    tasks[next_id] = task
    next_id += 1
    return {"id": next_id - 1, **task.model_dump()}

@app.delete("/tasks/{task_id}", status_code=204)
def delete_task(task_id: int):
    if tasks.pop(task_id, None) is None:
        raise HTTPException(status_code=404, detail="Nie ma takiego zadania")

3. Uruchom serwer deweloperski:

fastapi dev main.py

4. Otwórz http://127.0.0.1:8000/docs — FastAPI automatycznie generuje dokumentację w formacie OpenAPI, w której możesz klikać i testować endpointy.

Ten sam wzorzec znajdziesz w każdym frameworku: Express w Node.js, Spring Boot w Javie, ASP.NET Core w C# czy Laravel w PHP. Zmienia się składnia, ale zasoby, metody i kody statusu pozostają takie same. Logikę wspólną dla wielu endpointów, jak sprawdzanie tokenu czy logowanie zapytań, umieszcza się zwykle w middleware.

Nie zawsze trzeba pisać kod, żeby połączyć dwa systemy przez API. Platformy automatyzacji, takie jak n8n czy Make, wywołują endpointy REST z wizualnego edytora — to dobry sposób, by przetestować integrację, zanim zbudujesz własne rozwiązanie.

REST, SOAP, GraphQL czy gRPC — co wybrać

REST nie jest jedynym sposobem budowania API. Najczęściej porównuje się go z trzema alternatywami:

REST wygrywa prostotą, wsparciem cache’owania HTTP i tym, że da się go „przeklikać” w przeglądarce. GraphQL rozwiązuje problem pobierania zbyt wielu lub zbyt mało danych naraz. gRPC jest szybszy i ściśle typowany, ale trudniej go debugować i wywołać z przeglądarki. SOAP spotkasz głównie przy integracjach z dużymi, starszymi systemami — tam przyda się umiejętność czytania plików XML.

Plan nauki REST API krok po kroku

Jeśli zaczynasz, przejdź tę ścieżkę w tej kolejności:

1. Wyślij kilka zapytań GET, POST i DELETE do testowego API w curl i w Postmanie. Obserwuj nagłówki i kody statusu.
2. Podłącz się do prawdziwego publicznego API z dokumentacją (np. GitHub API, pogoda, kursy walut NBP) i przeczytaj, jak opisuje endpointy i uwierzytelnianie.
3. Napisz własne API z jednym zasobem (CRUD) w wybranym frameworku, najpierw w pamięci, potem z bazą danych.
4. Dodaj walidację danych, poprawne kody błędów, stronicowanie i uwierzytelnianie tokenem.
5. Opisz API w OpenAPI i dopisz testy automatyczne endpointów.

Po tych pięciu krokach będziesz rozumieć REST lepiej niż wiele osób, które używają go od lat, ale nigdy nie zajrzały, co dzieje się „pod spodem”.