0 dní v řadě · 0 bodů

Profesionální vývoj · 40 min

HTTP a návrh REST API

Jak vypadá požadavek a odpověď, co znamenají metody a stavové kódy a jak navrhnout API, které přežije výpadky i změny.

Hloubka
Úkoly
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:

http
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
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í:

  1. První řádek. U požadavku metoda, cesta a verze, u odpovědi verze a stavový kód.
  2. Hlavičky. Dvojice Jméno: hodnota s doplňujícími údaji.
  3. Prázdný řádek. Odděluje hlavičky od obsahu.
  4. 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))
Výstup
POST /ukoly HTTP/1.1
{'upozornit': ['1'], 'stitek': ['doma', 'rychle']}
application/json
{'nazev': 'Koupit mléko'}
znaků: 25 bajtů: 26

Dvě 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.

bash
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á.

Úkol

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
Výstup

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ÚčelBezpečnáIdempotentní
GETpřečti zdrojanoano
HEADjako GET, ale jen hlavičkyanoano
OPTIONSco je tu dovolenoanoano
PUTnahraď zdroj celýneano
DELETEsmaž zdrojneano
POSTvytvoř nebo spusť akcinene
PATCHzměň část zdrojenenení 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)
Výstup
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'}
Kvíz

Klient poslal DELETE /ukoly/5, spojení spadlo a odpověď nepřišla. Může požadavek bezpečně zopakovat?

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))
Výstup
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ódKdy ho použít
200povedlo se a v těle je výsledek
201vytvořeno, v hlavičce Location je adresa nového zdroje
204povedlo se, tělo je prázdné (typicky DELETE)
304nezměnilo se, použij svou uloženou kopii
400požadavek nejde vůbec přečíst, třeba rozbitý JSON
401nevím, kdo jsi: chybí nebo neplatí přihlášení
403vím, kdo jsi, ale tohle nesmíš
404taková věc tu není
405zdroj existuje, ale tuhle metodu nepodporuje
409koliduje to se současným stavem
422formát sedí, ale hodnoty neprošly kontrolou
429moc požadavků, zpomal
500chyba na straně serveru
503server 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í.

Kvíz

Přihlášený uživatel chce smazat cizí fakturu. Který kód je správný?

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 /vytvorUkolPOST /ukoly
GET /getUkol?id=5GET /ukoly/5
POST /smazUkol/5DELETE /ukoly/5
GET /ukoly/5/smazatDELETE /ukoly/5
GET /ukolyHotoveGET /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)
Výstup
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.

Úkol

JSON Merge Patch

Napiš funkci merge_patch(cil, zmena), která vrátí nový slovník a vstupy nezmění:

  • klíč s hodnotou None se z výsledku odstraní,
  • když je v zmena slovní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
Výstup
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.

Úkol

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ýš limit položek s id větším než po (bez po od začátku),
  • dalsi: id poslední vrácené položky, pokud za ní ještě něco je, jinak None.

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}
Výstup

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)
Výstup
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á.

python
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)))
Výstup
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)
Výstup
bez klíče: [500, 500]
{'platba': 1, 'castka': 500}
{'platba': 1, 'castka': 500}
s klíčem:  [500]
Kvíz

Proč se k čekání mezi pokusy přidává náhoda?

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)
Výstup
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.