Lidsky řečeno
Představ si úřad s přepážkou. Přijdeš s vyplněným formulářem: co chceš, jaké oddělení, pár kolonek a případně přílohu. Úředník vrátí papír s razítkem „vyřízeno“ nebo „chybí podpis“. A pamatuje si tě asi jako každý úředník, tedy vůbec, takže občanku ukazuješ pokaždé znovu. Přesně takhle funguje HTTP: formulář je požadavek, papír s razítkem odpověď a API je seznam přepážek, které úřad nabízí.
Požadavek a odpověď jsou text
HTTP je pravidlo, jak si dva programy po síti vyměňují zprávy. Klient (prohlížeč, mobilní aplikace, tvůj skript) se ptá, server odpovídá. API je rozhraní určené programům: místo hezké stránky vrací data, obvykle ve formátu JSON.
Takhle vypadá požadavek, když ho zbavíš všech vrstev:
POST /ukoly?upozornit=1 HTTP/1.1
Host: api.example.cz
Content-Type: application/json
Authorization: Bearer tajny-token
Content-Length: 26
{"nazev": "Koupit mléko"}A odpověď:
HTTP/1.1 201 Created
Content-Type: application/json
Location: /ukoly/42
{"id": 42, "nazev": "Koupit mléko", "hotovo": false}Skládá se ze čtyř částí:
- První řádek. U požadavku metoda, cesta a verze, u odpovědi verze a stavový kód.
- Hlavičky. Dvojice
Jméno: hodnotas doplňujícími údaji. - Prázdný řádek. Odděluje hlavičky od obsahu.
- Tělo. Vlastní data, může chybět.
Protože je to text, přečte ho i pár řádků Pythonu. Modul http.client umí hlavičky a urllib.parse adresy.
import io
import json
from http.client import parse_headers
from urllib.parse import parse_qs, urlsplit
telo = '{"nazev": "Koupit mléko"}'.encode("utf-8")
surovy = (
b"POST /ukoly?upozornit=1&stitek=doma&stitek=rychle HTTP/1.1\r\n"
b"Host: api.example.cz\r\n"
b"Content-Type: application/json\r\n"
+ f"Content-Length: {len(telo)}\r\n\r\n".encode()
+ telo
)
proud = io.BytesIO(surovy)
metoda, cil, verze = proud.readline().decode("ascii").split()
hlavicky = parse_headers(proud)
data = proud.read(int(hlavicky["Content-Length"]))
adresa = urlsplit(cil)
print(metoda, adresa.path, verze)
print(parse_qs(adresa.query))
print(hlavicky["content-type"])
print(json.loads(data))
print("znaků:", len(data.decode()), "bajtů:", len(data))
POST /ukoly HTTP/1.1
{'upozornit': ['1'], 'stitek': ['doma', 'rychle']}
application/json
{'nazev': 'Koupit mléko'}
znaků: 25 bajtů: 26Dvě věci stojí za povšimnutí. Jména hlaviček nerozlišují velikost písmen, proto zafungovalo content-type. A Content-Length udává bajty, ne znaky, takže é se počítá dvakrát.
Skutečný provoz si prohlédneš nástrojem curl, který je ve Windows, macOS i většině Linuxů. Přepínač -i vypíše i hlavičky odpovědi.
curl -i https://example.com/
curl -i -X POST https://api.example.cz/ukoly \
-H "Content-Type: application/json" \
-d '{"nazev": "Koupit mléko"}'Z Pythonu se volá přes knihovnu z lekce requests. Tady se díváme na druhou stranu: jak má vypadat API, které někdo volá.
Rozeber první řádek
Napiš funkci rozeber_radek(radek). Pro "GET /hledat?q=%C5%BEeb%C5%99%C3%ADk&limit=5 HTTP/1.1" vrátí n-tici ("GET", "/hledat", {"q": "žebřík", "limit": "5"}). Parametry dekóduj a hodnoty nech jako text. Když se parametr opakuje, platí poslední výskyt. Bez parametrů bude slovník prázdný.
from urllib.parse import urlsplit, parse_qsl
def rozeber_radek(radek):
return None
Metody: co s tím chceš udělat
Metoda říká, jaký je záměr. Důležité jsou dvě vlastnosti:
- Bezpečná metoda nemá na serveru měnit stav. Jen čte.
- Idempotentní metoda má stejný účinek, ať ji pošleš jednou, nebo desetkrát. Vypínač nastavený na „vypnuto“ je idempotentní. Tlačítko „přidej kus do košíku“ není.
| Metoda | Účel | Bezpečná | Idempotentní |
|---|---|---|---|
GET | přečti zdroj | ano | ano |
HEAD | jako GET, ale jen hlavičky | ano | ano |
OPTIONS | co je tu dovoleno | ano | ano |
PUT | nahraď zdroj celý | ne | ano |
DELETE | smaž zdroj | ne | ano |
POST | vytvoř nebo spusť akci | ne | ne |
PATCH | změň část zdroje | ne | není zaručeno |
Proč na tom záleží? Síť selhává. Když klient nedostane odpověď, neví, jestli požadavek došel. Idempotentní metodu může v klidu poslat znovu.
ukoly = {}
dalsi_id = 1
def post_ukol(nazev):
global dalsi_id
ukoly[dalsi_id] = nazev
dalsi_id += 1
def put_ukol(id_ukolu, nazev):
ukoly[id_ukolu] = nazev
for _ in range(3):
put_ukol(10, "Zalít kytky")
print("po 3x PUT: ", ukoly)
for _ in range(3):
post_ukol("Koupit mléko")
print("po 3x POST:", ukoly)
po 3x PUT: {10: 'Zalít kytky'}
po 3x POST: {10: 'Zalít kytky', 1: 'Koupit mléko', 2: 'Koupit mléko', 3: 'Koupit mléko'}Klient poslal DELETE /ukoly/5, spojení spadlo a odpověď nepřišla. Může požadavek bezpečně zopakovat?
Idempotence se týká stavu serveru, ne stejné odpovědi. Po prvním i druhém pokusu úkol 5 neexistuje.
Stavové kódy: razítko na odpovědi
Trojciferný stavový kód řekne výsledek ještě dřív, než klient otevře tělo. První číslice určuje třídu. V Pythonu jsou všechny v http.HTTPStatus.
from http import HTTPStatus
def trida(s):
if s.is_success:
return "úspěch"
if s.is_redirection:
return "jdi jinam"
if s.is_client_error:
return "chyba klienta"
if s.is_server_error:
return "chyba serveru"
return "informace"
for kod in [200, 201, 204, 304, 400, 401, 403, 404, 409, 422, 429, 500, 503]:
s = HTTPStatus(kod)
print(kod, f"{s.phrase:<24}", trida(s))
200 OK úspěch 201 Created úspěch 204 No Content úspěch 304 Not Modified jdi jinam 400 Bad Request chyba klienta 401 Unauthorized chyba klienta 403 Forbidden chyba klienta 404 Not Found chyba klienta 409 Conflict chyba klienta 422 Unprocessable Entity chyba klienta 429 Too Many Requests chyba klienta 500 Internal Server Error chyba serveru 503 Service Unavailable chyba serveru
| Kód | Kdy ho použít |
|---|---|
200 | povedlo se a v těle je výsledek |
201 | vytvořeno, v hlavičce Location je adresa nového zdroje |
204 | povedlo se, tělo je prázdné (typicky DELETE) |
304 | nezměnilo se, použij svou uloženou kopii |
400 | požadavek nejde vůbec přečíst, třeba rozbitý JSON |
401 | nevím, kdo jsi: chybí nebo neplatí přihlášení |
403 | vím, kdo jsi, ale tohle nesmíš |
404 | taková věc tu není |
405 | zdroj existuje, ale tuhle metodu nepodporuje |
409 | koliduje to se současným stavem |
422 | formát sedí, ale hodnoty neprošly kontrolou |
429 | moc požadavků, zpomal |
500 | chyba na straně serveru |
503 | server je dočasně nedostupný |
Zásadní dělítko: 4xx říká „oprav požadavek, opakování nepomůže“ a 5xx „problém je u nás, zkus to později“. Monitoring i klientské knihovny se podle toho řídí.
Přihlášený uživatel chce smazat cizí fakturu. Který kód je správný?
Identitu server zná, chybí mu oprávnění. 401 znamená, že se klient nepřihlásil nebo má neplatné údaje. Když nechceš prozradit, že faktura existuje, vrať 404.
Návrh REST API
REST je styl návrhu, ve kterém je všechno zdroj s vlastní adresou a s HTTP metodami jako jednotnými slovesy. Adresa tedy říká co, metoda co s tím.
| Špatně | Dobře |
|---|---|
POST /vytvorUkol | POST /ukoly |
GET /getUkol?id=5 | GET /ukoly/5 |
POST /smazUkol/5 | DELETE /ukoly/5 |
GET /ukoly/5/smazat | DELETE /ukoly/5 |
GET /ukolyHotove | GET /ukoly?hotovo=true |
Pravidla, která se vyplatí držet:
- Podstatná jména v množném čísle:
/ukoly,/ukoly/5. - Vztah vyjádři cestou, ale jen do jedné úrovně:
/projekty/3/ukoly. - Filtrování, řazení a stránkování patří do parametrů:
?hotovo=true&razeni=-vytvoreno&limit=20. - Akce, která se na CRUD nehodí, může být zdroj:
POST /objednavky/7/zruseni. - Jeden styl všude: stejné názvy polí, stejný formát data (ISO 8601), stejný tvar chyb.
Celé malé API se vejde do jedné funkce. Nepotřebuje síť: dostane metodu, cestu a tělo a vrátí odpověď. Tak se serverová logika i dobře testuje.
import json
import re
from dataclasses import dataclass, field
@dataclass
class Odpoved:
status: int
telo: object = None
hlavicky: dict = field(default_factory=dict)
ukoly = {1: {"id": 1, "nazev": "Koupit mléko", "hotovo": False}}
dalsi_id = 2
def problem(status, titulek, detail):
telo = {"type": "about:blank", "title": titulek, "status": status, "detail": detail}
return Odpoved(status, telo, {"Content-Type": "application/problem+json"})
def nacti_json(surove):
try:
data = json.loads(surove)
except (TypeError, ValueError):
return None
return data if isinstance(data, dict) else None
def zpracuj(metoda, cesta, surove=None):
global dalsi_id
if cesta == "/ukoly":
if metoda == "GET":
return Odpoved(200, {"data": list(ukoly.values())})
if metoda == "POST":
data = nacti_json(surove)
if data is None:
return problem(400, "Neplatný JSON", "Tělo musí být objekt JSON.")
nazev = data.get("nazev")
if not isinstance(nazev, str) or not nazev.strip():
return problem(422, "Neplatná data", "Pole nazev musí být neprázdný text.")
ukol = {"id": dalsi_id, "nazev": nazev.strip(), "hotovo": False}
ukoly[dalsi_id] = ukol
dalsi_id += 1
return Odpoved(201, ukol, {"Location": f"/ukoly/{ukol['id']}"})
return Odpoved(405, None, {"Allow": "GET, POST"})
nalez = re.fullmatch(r"/ukoly/(\d+)", cesta)
if nalez is None:
return problem(404, "Nenalezeno", f"Adresa {cesta} neexistuje.")
id_ukolu = int(nalez.group(1))
if id_ukolu not in ukoly:
return problem(404, "Nenalezeno", f"Úkol {id_ukolu} neexistuje.")
if metoda == "GET":
return Odpoved(200, ukoly[id_ukolu])
if metoda == "DELETE":
del ukoly[id_ukolu]
return Odpoved(204)
return Odpoved(405, None, {"Allow": "GET, DELETE"})
volani = [
("GET", "/ukoly/1", None),
("POST", "/ukoly", '{"nazev": "Zalít kytky"}'),
("POST", "/ukoly", '{"nazev": " "}'),
("POST", "/ukoly", "tohle není json"),
("PUT", "/ukoly", None),
("DELETE", "/ukoly/1", None),
("GET", "/ukoly/1", None),
]
for metoda, cesta, telo in volani:
o = zpracuj(metoda, cesta, telo)
print(metoda, cesta, "->", o.status, o.hlavicky or "")
if o.telo:
print(" ", o.telo.get("detail") or o.telo)
GET /ukoly/1 -> 200
{'id': 1, 'nazev': 'Koupit mléko', 'hotovo': False}
POST /ukoly -> 201 {'Location': '/ukoly/2'}
{'id': 2, 'nazev': 'Zalít kytky', 'hotovo': False}
POST /ukoly -> 422 {'Content-Type': 'application/problem+json'}
Pole nazev musí být neprázdný text.
POST /ukoly -> 400 {'Content-Type': 'application/problem+json'}
Tělo musí být objekt JSON.
PUT /ukoly -> 405 {'Allow': 'GET, POST'}
DELETE /ukoly/1 -> 204
GET /ukoly/1 -> 404 {'Content-Type': 'application/problem+json'}
Úkol 1 neexistuje.Chyby mají jednotný tvar application/problem+json podle RFC 9457. Klient tak nemusí pro každý endpoint psát vlastní zpracování. Stejnou logiku napíšeš pohodlně v FastAPI, které validaci a dokumentaci přidá samo.
PATCH potřebuje dohodu, jak změnu popsat. Nejjednodušší je JSON Merge Patch z RFC 7396: pošleš jen to, co se má změnit, a null znamená smazat.
JSON Merge Patch
Napiš funkci merge_patch(cil, zmena), která vrátí nový slovník a vstupy nezmění:
- klíč s hodnotou
Nonese z výsledku odstraní, - když je v
zmenaslovník, sloučí se rekurzivně s původní hodnotou (pokud původní hodnota slovník není, začíná se od prázdného), - cokoli jiného, včetně seznamů, původní hodnotu nahradí.
def merge_patch(cil, zmena):
vysledek = dict(cil)
vysledek.update(zmena)
return vysledek
Pod kapotou · pod HTTP a co říká specifikace
Sémantiku definuje RFC 9110, cache RFC 9111 a jednotlivé verze protokolu RFC 9112 (HTTP/1.1), 9113 (HTTP/2) a 9114 (HTTP/3). Metody a kódy jsou stejné, liší se přenos.
- HTTP/1.1 je textové, spojení je znovupoužitelné (keep-alive), ale odpovědi na něm chodí popořadě.
- HTTP/2 je binární a v jednom TCP spojení prokládá víc proudů. Ztracený TCP paket ale pořád zdrží všechny.
- HTTP/3 běží nad QUIC (UDP), kde ztráta brzdí jen dotčený proud a změna sítě nemusí přerušit spojení.
Request smuggling vzniká, když proxy a backend různě určí konec požadavku (Content-Length proti Transfer-Encoding: chunked). Část jednoho požadavku se pak přilepí k cizímu. Proto ručně psané parsování HTTP, které tu slouží k pochopení, do produkce nepatří.
Bezpečnost metody je kontrakt. GET, který něco maže, ti vyprázdní databázi, jakmile adresu navštíví crawler nebo prefetch v prohlížeči.
Dlouhé operace nedrž v otevřeném spojení. Vrať 202 Accepted s adresou stavového zdroje (Location: /ulohy/81) a klient se ptá, případně dostane webhook.
CORS není autorizace. Vynucuje ho prohlížeč a chrání uživatele před cizí stránkou, ne server před curlem. Credentials s Access-Control-Allow-Origin: * prohlížeč odmítne a reflektování libovolného Origin je běžná díra.
Token do hlavičky, nikdy do URL. Adresy končí v logech, historii a hlavičce Referer. Podrobnosti v lekci Bezpečnost.
API, které přežije realitu
Stránkování
Nikdy nevracej neomezený seznam. Klasické ?page=3 je jednoduché, ale když mezitím někdo přidá záznam, položky se posunou a klient některou uvidí dvakrát. Spolehlivější je kurzor: klient pošle, kde skončil.
Stránkování kurzorem
polozky je seznam slovníků seřazený podle id. Napiš funkci stranka(polozky, limit, po=None), která vrátí slovník:
data: nejvýšlimitpoložek sidvětším nežpo(bezpood začátku),dalsi:idposlední vrácené položky, pokud za ní ještě něco je, jinakNone.
Pozor na případ, kdy poslední stránka vyjde přesně na limit.
def stranka(polozky, limit, po=None):
return {"data": polozky[:limit], "dalsi": None}
Podmíněné požadavky a cache
ETag je otisk verze zdroje. Klient ho pošle zpátky v hlavičce If-None-Match, a pokud se nic nezměnilo, dostane 304 bez těla. Ušetří se přenos.
import hashlib
import json
def etag(data):
surove = json.dumps(data, sort_keys=True, ensure_ascii=False).encode()
return '"' + hashlib.sha256(surove).hexdigest()[:12] + '"'
zdroj = {"id": 1, "nazev": "Koupit mléko"}
def get(if_none_match=None):
aktualni = etag(zdroj)
if if_none_match == aktualni:
return 304, None, aktualni
return 200, zdroj, aktualni
status, telo, znacka = get()
print(status, telo, znacka)
status, telo, _ = get(if_none_match=znacka)
print(status, telo)
zdroj["nazev"] = "Koupit ovesné mléko"
status, telo, znacka = get(if_none_match=znacka)
print(status, telo, znacka)
200 {'id': 1, 'nazev': 'Koupit mléko'} "1b4df607e5ef"
304 None
200 {'id': 1, 'nazev': 'Koupit ovesné mléko'} "f6b4f7ad536e"Opakování a idempotenční klíč
Volání po síti musí mít časový limit, jinak může viset donekonečna. Knihovna requests žádný výchozí nemá.
import requests
odpoved = requests.get(
"https://api.example.cz/ukoly",
timeout=(3, 10), # 3 s na spojení, 10 s na čtení
)
odpoved.raise_for_status()Dočasné chyby (429, 502, 503, 504, výpadek spojení) má smysl opakovat, ale s rostoucím odstupem a kouskem náhody. Kdyby všichni klienti zkusili znovu ve stejnou chvíli, server, který se právě vzpamatovává, zase položí. Tomu se říká exponenciální backoff s jitterem.
import random
class Sluzba:
def __init__(self, vypadku):
self.vypadku = vypadku
def zavolej(self):
if self.vypadku > 0:
self.vypadku -= 1
return 503, None
return 200, {"ok": True}
def s_opakovanim(volani, rng, pokusu=5, zaklad=0.5, strop=8.0):
celkem = 0.0
for pokus in range(pokusu):
status, telo = volani()
print(f"pokus {pokus + 1}: {status}")
if status not in {429, 502, 503, 504}:
return status, telo, round(celkem, 2)
if pokus < pokusu - 1:
cekani = rng.uniform(0, min(strop, zaklad * 2**pokus))
print(f" čekám {cekani:.2f} s")
celkem += cekani
return status, telo, round(celkem, 2)
print(s_opakovanim(Sluzba(3).zavolej, random.Random(7)))
pokus 1: 503
čekám 0.16 s
pokus 2: 503
čekám 0.15 s
pokus 3: 503
čekám 1.30 s
pokus 4: 200
(200, {'ok': True}, 1.61)Co ale s platbou přes POST? Spojení spadne po odeslání a klient neví, jestli peníze odešly. Opakování by mohlo strhnout částku dvakrát. Řešením je idempotenční klíč: klient si vygeneruje jedinečný identifikátor operace a při opakování pošle stejný. Server si pamatuje výsledek.
platby = []
vysledky = {}
def zaplat(castka, klic=None):
if klic is not None and klic in vysledky:
return vysledky[klic]
platby.append(castka)
odpoved = {"platba": len(platby), "castka": castka}
if klic is not None:
vysledky[klic] = odpoved
return odpoved
zaplat(500)
zaplat(500)
print("bez klíče:", platby)
platby.clear()
print(zaplat(500, klic="a1f3"))
print(zaplat(500, klic="a1f3"))
print("s klíčem: ", platby)
bez klíče: [500, 500]
{'platba': 1, 'castka': 500}
{'platba': 1, 'castka': 500}
s klíčem: [500]Proč se k čekání mezi pokusy přidává náhoda?
Bez náhody by synchronizované vlny požadavků zasahovaly server přesně ve chvíli, kdy se zotavuje.
Pod kapotou · ztracené aktualizace, verzování a provozní detaily
Ztracená aktualizace. Dva lidé načtou stejný zdroj a oba uloží změnu. Ten druhý přepíše prvního. ETag funguje i opačným směrem: klient pošle If-Match a server při neshodě vrátí 412 Precondition Failed. Když hlavička chybí a ty ji vyžaduješ, je správně 428 Precondition Required.
import hashlib
zdroj = {"text": "původní"}
def znacka():
return hashlib.sha256(zdroj["text"].encode()).hexdigest()[:8]
def put(novy_text, if_match):
if if_match != znacka():
return 412
zdroj["text"] = novy_text
return 200
eva = marek = znacka()
print("Eva:", put("verze od Evy", eva))
print("Marek:", put("verze od Marka", marek))
print(zdroj)
Eva: 200
Marek: 412
{'text': 'verze od Evy'}Idempotenční klíč do produkce. Ukázka výše má závod: dva souběžné požadavky se stejným klíčem projdou oba. Klíč proto zapisuj atomicky, typicky unikátním indexem ve stejné databázové transakci jako samotnou operaci. Ulož i otisk těla a na stejný klíč s jinými daty odpověz chybou. Záznamy nech po čase vypršet. Hlavička Idempotency-Key je rozšířená konvence, kterou používají platební API, a její standardizace běží v IETF.
Cache. Cache-Control: max-age=60 dovolí 60 sekund se serveru neptat, no-cache znamená „ulož, ale pokaždé ověř“, no-store „neukládej“. Odpovědi závislé na přihlášení označ private. Hlavička Vary říká, které hlavičky požadavku mění odpověď. Když ji u Accept-Encoding nebo Authorization opomeneš, sdílená cache může doručit cizí obsah.
Verzování. Přidání nepovinného pole je kompatibilní. Odebrání, přejmenování, změna typu a nové povinné pole kompatibilní nejsou. Verze v cestě (/v1/) je nejviditelnější a nejsnáze se směruje. Klienti se ale spolehnou i na to, co jsi nikdy neslíbil, včetně pořadí polí nebo textu chyb (Hyrumův zákon). Stažení verze ohlas předem, například hlavičkou Sunset (RFC 8594), a sleduj, kdo starou verzi ještě volá.
Retry budget a deadline. Místo pevného počtu pokusů povol opakování jen pro malý podíl provozu, jinak se při výpadku zátěž znásobí. Termín předávej mezi službami, ať backend nepočítá odpověď, na kterou už nikdo nečeká. U 429 vracej Retry-After. Přesně vzato může mít tvar sekund i data, takže klient musí umět oba.
Vyzkoušej si: Požadavek a odpověď
Poskládej metodu, cestu, hlavičky a tělo a podívej se na surový požadavek i odpověď ukázkového API v paměti.