Slovenská verzeSK

Stavové kódy

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
Miroslav Holec

Miroslav Holec

24. března 2021

👮‍♂️ Seriál REST API

  1. Historie REST API
  2. Stavové kódy
Loading