Jan Mikoláš
Slovník pojmů
HTTP stavový kód
Stavový kód popisuje HTTP výsledek requestu, ne celý příběh business procesu. „Přijato k asynchronnímu zpracování“ a „objednávka byla doručena“ jsou rozdílné informace.
Stručná definice
Krátký standardní signál o tom, co server s requestem provedl.
HTTP response začíná stavovým kódem v rozsahu 100 až 599. První číslice určuje třídu: informační 1xx, úspěch 2xx, přesměrování 3xx, chyba na straně klienta 4xx a chyba serveru 5xx. Konkrétní kód spolu s metodou, hlavičkami a tělem odpovědi říká klientovi, zda má výsledek použít, opravit vstup, přihlásit se, následovat redirect nebo řešit dočasnou chybu.
Správný status není dekorace pro monitoring. Mění chování prohlížeče, HTTP klienta, cache a retry mechanismu. Odpověď 200 s chybou schovanou v JSONu komplikuje automatické klienty i observabilitu. Stejně nepřesné je vracet 500 pro chybný vstup, který klient může opravit, nebo 404 pro zákaz přístupu, pokud tím nechtěně prozradíme existenci zdroje.
K čemu se používá
Pro čitelné výsledky webu, API a integrace
Kód se vybírá podle výsledku konkrétního HTTP requestu, ne podle oblíbeného seznamu čísel.
- úspěšné načtení nebo změna zdroje v administraci a API
- oznámení vytvoření nového zdroje včetně jeho Location
- asynchronní přijetí importu nebo exportu, který bude dokončen workerem
- rozlišení neplatného vstupu, chybějící autentizace, oprávnění a konfliktu stavu
- monitoring dostupnosti, chyb upstreamu a řízené retry integračního klienta
Praktický příklad
Asynchronní import katalogu
Partner odešle katalog, jehož ověření a zpracování poběží několik minut. API po základní validaci vytvoří úlohu a vrátí 202 Accepted se zdrojem úlohy v hlavičce Location. Klient ví, že request byl přijat, ale ještě nemá tvrdit, že katalog je hotový.
Pokud je JSON syntakticky neplatný, API vrátí 400. Pokud je JSON platný, ale obsahuje neexistující měnu nebo nesplňuje pravidlo katalogu, kontrakt může vrátit 422 a strukturovaně označit dotčené pole. Oba případy jsou pro klienta opravitelné, proto nejde o 500.
HTTP/1.1 202 Accepted
Location: /api/import-jobs/imp_42
Content-Type: application/json
{"id":"imp_42","status":"queued"}
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json
{"code":"invalid_currency","field":"items[0].currency"}Jak funguje
Od výsledku aplikačního kroku k reakci klienta
Status je souhrn HTTP výsledku; detail pro člověka nebo program patří do stabilního těla odpovědi.
- Request dorazí k aplikaci Aplikace zjistí, zda metoda a cesta existují, ověří identitu, oprávnění a vstupní data.
- Vyhodnotí se konkrétní výsledek Může vzniknout zdroj, být přijata asynchronní práce, narazit validace nebo selhat závislý server.
- Zvolí se status a metadata Server přidá například Location po vytvoření, WWW-Authenticate při potřebě přihlášení nebo Retry-After při řízeném odložení.
- Response nese detail JSON či HTML vysvětlí bezpečný detail chyby. Interní stack trace, SQL a tajemství do veřejné odpovědi nepatří.
- Klient reaguje podle kontraktu Zobrazí chybu, obnoví přihlášení, následuje redirect, naplánuje retry nebo pokračuje s obdrženou reprezentací.
Hlavní části a pojmy
Třída kódu je začátek, konkrétní semantika rozhoduje.
U API se opakovaně objevuje několik kódů, jejichž záměna dává klientovi špatný návod.
Úspěch 2xx
200 obvykle vrací reprezentaci. 201 znamená vytvoření zdroje a běžně se doplňuje Location. 202 říká, že request byl přijat k dalšímu zpracování, nikoli že hotová práce už skončila. 204 potvrzuje úspěch bez těla response.
Přesměrování 3xx
Redirect je instrukce pro klienta, aby provedl další krok podle Location. Kód se volí s ohledem na metodu a očekávané zachování či změnu requestu; není to náhrada pro vracení chybného URL v JSONu.
Autentizace a oprávnění
401 znamená, že request nemá platné autentizační údaje, a může doplnit WWW-Authenticate. 403 znamená, že server request pochopil, ale odmítl jej autorizovat. Kontrakt může vědomě použít 404, pokud nesmí odhalit existenci citlivého zdroje.
Vstup a konflikt
400 se používá pro chybný request na úrovni HTTP nebo obecně nevalidní vstup podle kontraktu. 409 označuje konflikt s aktuálním stavem zdroje. 422 může popsat srozumitelný request, jehož instrukci nelze zpracovat kvůli významové validaci.
Chyba serveru a retry
5xx signalizuje, že klient poslal zdánlivě platný request, ale server jej nedokázal splnit. Retry se neřídí jen třídou 5xx: záleží na metodě, idempotenci, časovém limitu a pokynech služby.
Vztah k ostatním pojmům
Status, hlavičky a tělo tvoří jednu odpověď.
Klient se nesmí rozhodovat jen podle lidského textu za stavovým kódem.
- HTTP
- Protokol definuje třídy a semantiku statusů v request–response komunikaci.
- HTTP hlavička
- Location, Retry-After nebo WWW-Authenticate dokreslují význam konkrétní response.
- REST API
- REST rozhraní používá HTTP statusy při práci se zdroji, ale potřebuje i vlastní konzistentní chybový formát.
- Retry a idempotence
- Timeout nebo 5xx nesmí automaticky znamenat bezpečné opakování zápisového requestu.
Výhody a omezení
Krátký standardní kód potřebuje doplnit konkrétním detailem.
Přínosy
- standardní reakce pro browser, HTTP klient, cache a monitoring
- lepší rozlišení chyb klienta a chyb infrastruktury
- možnost bezpečně řídit vytvoření zdroje, redirect i asynchronní přijetí práce
- čitelnější metriky a alerty bez parsování volného textu JSONu
Omezení a časté chyby
- 200 s chybovým objektem místo odpovídající 4xx či 5xx
- 202 vydávaná za dokončený asynchronní proces
- 401 a 403 používané zaměnitelně bez kontextu autentizace
- retry každé 5xx odpovědi u ne-idempotentního zápisu
- příliš detailní chybové zprávy prozrazující interní data nebo existenci zdroje
Kdy dává smysl
Vždy, když HTTP response potřebuje být strojově srozumitelná.
Statusové kódy patří na každou HTTP odpověď, ale jejich význam se navrhuje na úrovni endpointu a dokumentovaného kontraktu. E-shop může při vytvoření objednávky vrátit 201, při přijetí dlouhého importu 202 a při konfliktu verze objednávky 409. Detail konkrétního problému pak vrací stabilní JSON struktura, ne náhodný překlad textu.
Kód sám nepopisuje celý business stav. Zpracování objednávky může být technicky přijato s 202 a později skončit neúspěchem. API proto obvykle vrátí identifikátor úlohy nebo zdroje, na kterém klient stav zjistí. To je přesnější než předstírat úspěch 200 jen proto, že HTTP spojení fungovalo.
Na co myslet
Volit kód podle výsledku requestu a testovat jej jako kontrakt.
Konzistence není o tom, aby každý endpoint použil stejný kód, ale aby stejná situace měla stejný význam.
- pro vytvořený zdroj vracet 201 a podle potřeby Location, pro přijatou dlouhou práci 202
- rozlišit chybějící či neplatnou autentizaci, nedostatečné oprávnění, validaci a konflikt stavu
- držet veřejné tělo chyby stabilní, bezpečné a užitečné pro klienta
- při retry hodnotit idempotenci operace, nikoli pouze stavový kód
- zahrnout statusy a klíčové hlavičky do integračních testů, monitoringu a dokumentace API
Časté otázky
Jak číst výsledky API
Jaký je rozdíl mezi 200, 201 a 204?
200 obvykle vrací úspěšnou reprezentaci. 201 říká, že vznikl nový zdroj, často s Location. 204 potvrzuje úspěch, ale response nemá tělo.
Jaký je rozdíl mezi 401 a 403?
401 znamená chybějící nebo neplatnou autentizaci. 403 znamená, že server identitu rozpoznal, ale danou akci nepovolil.
Znamená 202, že import už proběhl?
Ne. Znamená, že server request přijal k dalšímu zpracování. Klient má zjistit stav z úlohy nebo jiného dokumentovaného zdroje.
Mohu po každé 500 odpovědi request opakovat?
Ne automaticky. Je potřeba znát idempotenci operace, případný idempotency key a pravidla retry. Jinak se může dvakrát založit objednávka nebo odeslat platba.
Jak pracuji s API v praxi
Odpovědi API navrhuji pro klienta, provoz i bezpečný retry.
V integračních službách řeším statusy, chybové kontrakty, asynchronní zpracování i idempotenci tak, aby výsledek requestu neklamal uživatele ani další systém.