Kurs Python · Moduł 4: Dane, API i bazy danych
REST API - architektura wymiany danych
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 lwaPOST /api/species- utwórz gatunekDELETE /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
| Metoda | Akcja | Przykład |
|---|---|---|
| GET | Pobierz zasób/zasoby | GET /species - lista, GET /species/lion - jeden |
| POST | Utwórz nowy zasób | POST /species - dodaj gatunek |
| PUT | Zastąp cały zasób | PUT /species/lion - zastąp dane lwa |
| PATCH | Zaktualizuj część zasobu | PATCH /species/lion - zmień populację |
| DELETE | Usuń zasób | DELETE /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 abc123Serwer 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 SerengetiZasada: /zasób/id/podzasób/id
5. Wersjonowanie API
API ewoluuje - wersjonowanie zapobiega zepsuciu starych klientów:
/api/v1/species
/api/v2/speciesZmiana 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-31Sortowanie
# 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,populationPaginacja
# 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_hereBearer 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/cheetah8. Rate limiting - komunikuj limity
Response Headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000Podsumowanie
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 /speciesaGET /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. REST to skrót od:
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: