Stavové kódy

Miroslav Holec 24. března 2021

Tento článek je již zastaralý. Článek nemusí popisovat aktuální stav technologie, ideální řešení a můj současný pohled na dané téma.

Stavové kódy využívá HTTP protokol jako indikátor výsledku zpracování požadavku na straně serveru. Z pohledu REST API je každé volání z klienta na server atomické a tudíž i výsledek zpracování požadavku je vždy zcela jednoznačný s ohledem na prováděnou operaci nad resource. Dle současného standardu (RFC 7231) musí klient obdržet ze strany serveru minimálně kategoricky správně zařaditelný stavový kód s ohledem na výsledek požadavku. RFC definuje stavový kód jako třímístné číslo, ve kterém první číslice zleva označuje kategorii.

Kategorizace stavových kódů

1xx - informativní
2xx - úspěch
3xx - redirection
4xx - chyba na straně klienta
5xx - chyba na straně serveru

V praxi však REST API kladou na vývojáře požadavek na využití i konkrétních stavových kódů. Mezi nejčastější případy s ohledem na RFC uveďme:

201 - indikuje úspěšné vytvoření resource, typicky ve spojení s metodou POST nebo PUT
202 - indikuje, že požadavek byl přijat ke zpracování, které dosud nebylo dokončeno
204 - indikuje úspěšně provednou operaci, která nevrací žádný obsah (payload)
304 - indikuje, že resource nebyl změněn a klient může použít starší kopii dat (cache)
401 - klient nebyl úspěšně autentizován
403 - klient není autorizován k provedení požadavku
404 - resource nebyl nalezen

Konkrétní stavový kód může mít pro klienta důležitý význam v případě často užívané metody PUT. Za předpokladu idempotentní implementace může nad jedním resource proběhnout PUT operace za účelem vytvoření nebo za účelem aktualizace resource. Stavovým kódem 200 pak server indikuje úspěšnou aktualizaci, zatímco stavovým kódem 201 indikuje úspěšné vytvoření nového resource.

Souvislost s HTTP hlavičkami

Určité stavové kódy dále z pohledu RFC kladou požadavek nebo doporučení pro připojení metadat v podobě HTTP hlaviček. Příkladem budiž stavový kód 301 - permanentně přesunutý resource. RFC doporučuje (SHOULD), že by server měl generovat současně HTTP hlavičku Location, čímž umožňuje klientovi (MAY) provést redirect na tuto uvedenou lokaci.

Různé stavové kódy mají dále vliv na cache-ovatelnost požadavků. Ve výše uvedeném příkladu RFC předpokládá, že operace ukončená status kódem 301 je cache-ovatelná.

Zdroje

https://tools.ietf.org/html/rfc7231