Kurs Python · Moduł 4: Dane, API i bazy danych

REST API - architektura wymiany danych

11 min czytania ·
W tej lekcji11

Witaj z powrotem! Darwin tutaj z kolejną lekcją o przepływie danych.

Nauczyłeś/aś się formatów danych (JSON, CSV, XML) i protokołu HTTP (GET, POST, PUT, DELETE). Teraz czas na REST API - standardową architekturę budowania API, którą używa się na całym świecie!

Analogia Safari: HTTP to system kurierski. REST API to standardowe procedury - zasady, według których organizujesz stacje badawcze, katalogi danych i komunikację między nimi. Dzięki tym zasadom każdy biolog, niezależnie skąd pochodzi, wie jak pobrać dane o lwach: GET /api/species/lion

Czym jest REST API?

REST (REpresentational State Transfer) to styl architektury dla API - zbiór zasad i konwencji, jak projektować API wykorzystujące HTTP.

API (Application Programming Interface) to interfejs programistyczny - sposób, w jaki aplikacje rozmawiają ze sobą.

REST API = HTTP API zaprojektowane według zasad REST

Po co REST?

Bez standardów każde API wyglądałoby inaczej:

  • /getLion?id=123
  • /fetchLionData
  • /lion-information/get
  • /api/v1/animals/lion/retrieve

Z REST wszyscy wiedzą:

  • GET /api/species/lion - pobierz lwa
  • POST /api/species - utwórz gatunek
  • DELETE /api/species/lion - usuń lwa

Przewidywalne, spójne, intuicyjne!

Zasady REST

1. Zasoby (Resources) - rzeczowniki, nie czasowniki

W REST wszystko to zasób (resource) - obiekt, encja, dane.

Dobre - rzeczowniki:

  • /species - gatunek
  • /observations - obserwacje
  • /habitats - siedliska
  • /researchers - badacze

Złe - czasowniki:

  • /getSpecies
  • /createObservation
  • /deleteHabitat

Akcja określona przez metodę HTTP, nie URL!

2. Metody HTTP = akcje na zasobach

MetodaAkcjaPrzykład
GETPobierz zasób/zasobyGET /species - lista, GET /species/lion - jeden
POSTUtwórz nowy zasóbPOST /species - dodaj gatunek
PUTZastąp cały zasóbPUT /species/lion - zastąp dane lwa
PATCHZaktualizuj część zasobuPATCH /species/lion - zmień populację
DELETEUsuń zasóbDELETE /species/lion - usuń lwa

3. Stateless - bezstanowość

Każde zapytanie musi zawierać wszystkie informacje potrzebne do jego obsłużenia. Serwer nie pamięta poprzednich zapytań.

Przykład:

# Każde zapytanie zawiera token autoryzacji
GET /api/species/lion
Authorization: Bearer abc123

GET /api/observations
Authorization: Bearer abc123

Serwer nie wie "kto to wysłał wcześniej" - każde zapytanie samodzielne!

4. Hierarchia zasobów

Zasoby mogą być zagnieżdżone hierarchicznie:

/species/lion                    # Gatunek: lew
/species/lion/observations       # Obserwacje lwa
/species/lion/observations/123   # Konkretna obserwacja lwa #123

/habitats/serengeti              # Siedlisko: Serengeti
/habitats/serengeti/species      # Gatunki w Serengeti

Zasada: /zasób/id/podzasób/id

5. Wersjonowanie API

API ewoluuje - wersjonowanie zapobiega zepsuciu starych klientów:

/api/v1/species
/api/v2/species

Zmiana wersji gdy:

  • Usuwasz pola z odpowiedzi
  • Zmieniasz format danych
  • Usuwasz endpointy

RESTful Endpoints - standardowe wzorce

CRUD (Create, Read, Update, Delete) dla zasobu

# LIST - lista wszystkich gatunków
GET /api/species
Response: [{"id": "lion", "name": "Lew"}, {"id": "elephant", "name": "Słoń"}]

# GET - jeden gatunek
GET /api/species/lion
Response: {"id": "lion", "scientific_name": "Panthera leo", "population": 120}

# CREATE - utwórz nowy gatunek
POST /api/species
Body: {"scientific_name": "Gorilla gorilla", "population": 230}
Response: {"id": "gorilla", "scientific_name": "Gorilla gorilla", "population": 230}

# UPDATE (całość) - zastąp gatunek
PUT /api/species/lion
Body: {"scientific_name": "Panthera leo", "population": 125, "habitat": "savanna"}
Response: {"id": "lion", ...}

# UPDATE (część) - zmień tylko populację
PATCH /api/species/lion
Body: {"population": 125}
Response: {"id": "lion", "population": 125, ...}

# DELETE - usuń gatunek
DELETE /api/species/lion
Response: 204 No Content (lub 200 z potwierdzeniem)

Zasoby zagnieżdżone (nested resources)

# Lista obserwacji dla lwa
GET /api/species/lion/observations
Response: [
  {"id": "obs1", "date": "2024-01-15", "count": 12},
  {"id": "obs2", "date": "2024-01-20", "count": 8}
]

# Konkretna obserwacja lwa
GET /api/species/lion/observations/obs1
Response: {"id": "obs1", "species": "lion", "date": "2024-01-15", "count": 12}

# Dodaj obserwację dla lwa
POST /api/species/lion/observations
Body: {"date": "2024-01-25", "count": 10, "location": "Serengeti"}
Response: {"id": "obs3", "species": "lion", ...}

Query Parameters - filtrowanie, sortowanie, paginacja

Filtrowanie

# Gatunki zagrożone
GET /api/species?endangered=true

# Gatunki w sawannie z populacją > 100
GET /api/species?habitat=savanna&min_population=100

# Obserwacje z zakresu dat
GET /api/observations?start_date=2024-01-01&end_date=2024-01-31

Sortowanie

# Sortuj według populacji rosnąco
GET /api/species?sort=population

# Sortuj według populacji malejąco
GET /api/species?sort=-population

# Sortuj po nazwie, potem populacji
GET /api/species?sort=name,population

Paginacja

# Strona 1, 20 wyników na stronę
GET /api/species?page=1&per_page=20

# Alternatywnie: offset i limit
GET /api/species?offset=0&limit=20

# Odpowiedź z metadanymi paginacji:
{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_items": 150,
    "total_pages": 8
  }
}

Wybór pól (field selection)

# Tylko nazwa i populacja
GET /api/species?fields=name,population

Response: [
  {"name": "Lew", "population": 120},
  {"name": "Słoń", "population": 450}
]

Struktura odpowiedzi JSON

Sukces - pojedynczy zasób

{
  "id": "lion",
  "scientific_name": "Panthera leo",
  "common_name": "Lew",
  "population": 120,
  "habitat": "sawanna",
  "endangered": true,
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-15T14:30:00Z"
}

Sukces - lista zasobów z paginacją

{
  "data": [
    {"id": "lion", "name": "Lew", "population": 120},
    {"id": "elephant", "name": "Słoń", "population": 450}
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 45,
    "pages": 3
  },
  "links": {
    "self": "/api/species?page=1",
    "next": "/api/species?page=2",
    "last": "/api/species?page=3"
  }
}

Błąd - standardowy format

{
  "error": {
    "code": "SPECIES_NOT_FOUND",
    "message": "Gatunek 'unicorn' nie istnieje",
    "status": 404,
    "timestamp": "2024-01-15T14:30:00Z"
  }
}

Błędy walidacji

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Błędy walidacji danych",
    "status": 400,
    "details": [
      {"field": "population", "message": "Musi być liczbą większą od 0"},
      {"field": "habitat", "message": "Pole wymagane"}
    ]
  }
}

Kody statusu HTTP w REST

2xx - Sukces

  • 200 OK - GET, PUT, PATCH - sukces z danymi
  • 201 Created - POST - zasób utworzony (+ nagłówek Location)
  • 204 No Content - DELETE - sukces bez danych

4xx - Błąd klienta

  • 400 Bad Request - błędne dane (np. zły JSON, walidacja)
  • 401 Unauthorized - brak uwierzytelnienia
  • 403 Forbidden - brak uprawnień (uwierzytelniony, ale nie ma dostępu)
  • 404 Not Found - zasób nie istnieje
  • 409 Conflict - konflikt (np. duplikat ID)
  • 422 Unprocessable Entity - prawidłowy format, ale logicznie błędne dane
  • 429 Too Many Requests - rate limit przekroczony

5xx - Błąd serwera

  • 500 Internal Server Error - błąd serwera
  • 503 Service Unavailable - serwis niedostępny

Autentykacja i autoryzacja

API Key

GET /api/species
X-API-Key: your_api_key_here

Bearer Token (JWT)

GET /api/species
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Basic Auth

GET /api/species
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Najczęściej: Bearer Token (OAuth 2.0, JWT)

Safari przykład - pełne REST API klienta

import requests
from typing import List, Dict, Optional, Any
from datetime import datetime

class SafariRESTClient:
    """REST API klient dla Safari Data API"""

    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url.rstrip("/")
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Accept": "application/json",
            "Content-Type": "application/json"
        })

    # === SPECIES - /api/species ===

    def list_species(self, habitat: Optional[str] = None,
                    endangered: Optional[bool] = None,
                    page: int = 1, per_page: int = 20,
                    sort: str = "name") -> Dict[str, Any]:
        """
        GET /api/species
        Lista gatunków z filtrowaniem, sortowaniem, paginacją
        """
        params = {
            "page": page,
            "per_page": per_page,
            "sort": sort
        }
        if habitat:
            params["habitat"] = habitat
        if endangered is not None:
            params["endangered"] = str(endangered).lower()

        response = self.session.get(f"{self.base_url}/api/species", params=params)
        response.raise_for_status()
        return response.json()

    def get_species(self, species_id: str) -> Dict[str, Any]:
        """
        GET /api/species/{id}
        Pobierz pojedynczy gatunek
        """
        response = self.session.get(f"{self.base_url}/api/species/{species_id}")
        response.raise_for_status()
        return response.json()

    def create_species(self, data: Dict[str, Any]) -> Dict[str, Any]:
        """
        POST /api/species
        Utwórz nowy gatunek
        """
        response = self.session.post(f"{self.base_url}/api/species", json=data)
        response.raise_for_status()

        if response.status_code == 201:
            # Zwróć utworzony zasób + ID z Location header
            location = response.headers.get("Location")
            print(f"Utworzono: {location}")

        return response.json()

    def update_species(self, species_id: str, data: Dict[str, Any]) -> Dict[str, Any]:
        """
        PUT /api/species/{id}
        Zastąp cały gatunek
        """
        response = self.session.put(
            f"{self.base_url}/api/species/{species_id}",
            json=data
        )
        response.raise_for_status()
        return response.json()

    def partial_update_species(self, species_id: str,
                              data: Dict[str, Any]) -> Dict[str, Any]:
        """
        PATCH /api/species/{id}
        Zaktualizuj część gatunku
        """
        response = self.session.patch(
            f"{self.base_url}/api/species/{species_id}",
            json=data
        )
        response.raise_for_status()
        return response.json()

    def delete_species(self, species_id: str) -> bool:
        """
        DELETE /api/species/{id}
        Usuń gatunek
        """
        response = self.session.delete(f"{self.base_url}/api/species/{species_id}")
        response.raise_for_status()
        return response.status_code == 204

    # === OBSERVATIONS - /api/species/{id}/observations ===

    def list_observations(self, species_id: str,
                         start_date: Optional[str] = None,
                         end_date: Optional[str] = None,
                         page: int = 1) -> Dict[str, Any]:
        """
        GET /api/species/{id}/observations
        Lista obserwacji dla gatunku
        """
        params = {"page": page}
        if start_date:
            params["start_date"] = start_date
        if end_date:
            params["end_date"] = end_date

        response = self.session.get(
            f"{self.base_url}/api/species/{species_id}/observations",
            params=params
        )
        response.raise_for_status()
        return response.json()

    def create_observation(self, species_id: str,
                          data: Dict[str, Any]) -> Dict[str, Any]:
        """
        POST /api/species/{id}/observations
        Dodaj obserwację dla gatunku
        """
        response = self.session.post(
            f"{self.base_url}/api/species/{species_id}/observations",
            json=data
        )
        response.raise_for_status()
        return response.json()

    def get_observation(self, species_id: str, observation_id: str) -> Dict[str, Any]:
        """
        GET /api/species/{id}/observations/{obs_id}
        Pobierz konkretną obserwację
        """
        response = self.session.get(
            f"{self.base_url}/api/species/{species_id}/observations/{observation_id}"
        )
        response.raise_for_status()
        return response.json()

    # === STATISTICS - /api/statistics ===

    def get_statistics(self, group_by: str = "habitat") -> Dict[str, Any]:
        """
        GET /api/statistics
        Pobierz statystyki
        """
        params = {"group_by": group_by}
        response = self.session.get(
            f"{self.base_url}/api/statistics",
            params=params
        )
        response.raise_for_status()
        return response.json()

    def close(self):
        """Zamknij sesję"""
        self.session.close()


# === DEMONSTRACJA ===

print("=== SAFARI REST API CLIENT ===\n")

client = SafariRESTClient(
    base_url="https://api.safari-data.org",
    api_key="demo_bearer_token_12345"
)

# 1. LIST - pobierz wszystkie gatunki zagrożone w sawannie
print("1. Lista gatunków (filtrowane, sortowane, paginowane)")
result = client.list_species(
    habitat="savanna",
    endangered=True,
    page=1,
    per_page=10,
    sort="-population"  # Malejąco według populacji
)

print(f"   Znaleziono: {result['pagination']['total']} gatunków")
for species in result['data']:
    print(f"   - {species['common_name']}: {species['population']} osobników")

# 2. GET - pobierz konkretny gatunek
print("\n2. Pobieranie konkretnego gatunku")
lion = client.get_species("lion")
print(f"   {lion['common_name']} ({lion['scientific_name']})")
print(f"   Populacja: {lion['population']}")
print(f"   Zagrożony: {'Tak' if lion['endangered'] else 'Nie'}")

# 3. POST - utwórz nowy gatunek
print("\n3. Tworzenie nowego gatunku")
new_species = {
    "scientific_name": "Acinonyx jubatus",
    "common_name": "Gepard",
    "population": 7100,
    "habitat": "sawanna",
    "endangered": True
}

created = client.create_species(new_species)
print(f"   Utworzono: {created['common_name']} (ID: {created['id']})")

# 4. PATCH - zaktualizuj tylko populację
print("\n4. Częściowa aktualizacja (PATCH)")
updated = client.partial_update_species("lion", {"population": 125})
print(f"   Zaktualizowano populację: {updated['population']}")

# 5. Obserwacje zagnieżdżone - lista
print("\n5. Lista obserwacji dla lwa")
observations = client.list_observations(
    "lion",
    start_date="2024-01-01",
    end_date="2024-01-31"
)

print(f"   Znaleziono {len(observations['data'])} obserwacji w styczniu")
for obs in observations['data']:
    print(f"   - {obs['date']}: {obs['count']} osobników w {obs['location']}")

# 6. Obserwacje zagnieżdżone - tworzenie
print("\n6. Dodawanie nowej obserwacji")
new_obs = {
    "date": datetime.now().isoformat(),
    "location": "Serengeti North",
    "count": 15,
    "notes": "Pride with 3 cubs"
}

obs_created = client.create_observation("lion", new_obs)
print(f"   Utworzono obserwację ID: {obs_created['id']}")

# 7. Statystyki
print("\n7. Pobieranie statystyk")
stats = client.get_statistics(group_by="habitat")
print("   Statystyki według siedliska:")
for habitat_stat in stats['data']:
    print(f"   - {habitat_stat['habitat']}: {habitat_stat['species_count']} gatunków")

# 8. DELETE - usuń gatunek
print("\n8. Usuwanie gatunku")
if client.delete_species("test-species"):
    print("   Gatunek usunięty")

client.close()
print("\nDemonstracja zakończona")

Best Practices REST API

1. Używaj rzeczowników w liczbie mnogiej

/api/species, /api/observations /api/specie, /api/observation

2. Zawsze wersjonuj API

/api/v1/species /api/species (co gdy zmienisz format?)

3. Hierarchia zasobów nie głębsza niż 2 poziomy

/species/lion/observations /continents/africa/countries/kenya/parks/serengeti/species/lion/observations

4. Używaj snake_case lub camelCase - konsekwentnie

{"scientific_name": "..."} lub {"scientificName": "..."} {"scientific_name": "...", "commonName": "..."} - mieszane!

5. Filtry, sortowanie, paginacja przez query params

GET /species?habitat=savanna&sort=-population&page=2 POST /species/filter z body

6. Zwracaj odpowiednie kody statusu

  • 201 Created (nie 200) dla POST
  • 204 No Content dla DELETE
  • 404 Not Found gdy zasób nie istnieje
  • 400 Bad Request dla błędów walidacji

7. Używaj nagłówka Location dla nowych zasobów

POST /api/species
Response: 201 Created
Location: /api/species/cheetah

8. Rate limiting - komunikuj limity

Response Headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

Podsumowanie

W tej lekcji nauczyłeś/aś się:

  • Czym jest REST API i po co służy
  • Zasady REST: zasoby, metody HTTP, stateless, hierarchia
  • RESTful endpoints: /api/v1/resources/:id
  • CRUD operations: GET, POST, PUT, PATCH, DELETE
  • Query parameters: filtrowanie, sortowanie, paginacja
  • Struktura odpowiedzi JSON (data, pagination, error)
  • Kody statusu w kontekście REST
  • Autentykacja: API Key, Bearer Token
  • Best practices dla REST API

Checkpoint

Przed przejściem dalej:

  • Rozumiesz różnicę między POST /species a GET /species/{id}
  • Potrafisz zaprojektować RESTful endpoint
  • Wiesz jak używać query params do filtrowania
  • Rozumiesz zasoby zagnieżdżone (/species/{id}/observations)
  • Znasz best practices REST API

Analogia Safari: REST API to uniwersalne standardy komunikacji między stacjami badawczymi na całym świecie. Dzięki nim biolog z Polski wie, że GET /api/species/lion zwróci dane lwa - bez względu na to, kto zbudował API!

W następnej lekcji Darwin nauczy Cię web scrapingu - jak zbierać dane ze stron internetowych, które nie mają API!

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. REST to skrót od:

  2. 2. Która metoda HTTP odpowiada operacji UPDATE w CRUD?

To 2 z 4 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Edytor kodu

    Wyślij POST z danymi animal = {'name': 'Tygrys'} na URL '/api/animals'

  • Edytor kodu

    Wyślij GET z headerem Authorization: Bearer token123

  • Układanie w pionie

    Uporządkuj etapy zapytania HTTP:

  • Układanie w poziomie

    Ułóż elementy w prawidłowej kolejności:

  1. PytanieREST
  2. PytanieCRUD operations
  3. PytaniePOST request
  4. Zadanie z kodemPOST request
  5. Zadanie z kodemHeaders w request
  6. Ułóż w kolejnościHTTP request lifecycle
  7. Ułóż w kolejnościJSON loads
  8. PytanieCRUD - litera C

Przydatne artykuły