Slovník pojmů

HTTP hlavička

HTTP hlavičky doplňují tělo zprávy o tom, jak jej interpretovat, kdo může odpověď použít a jak se má request zpracovat. Hodnota poslaná klientem ale není sama o sobě důvěryhodná.

Stručná definice

Pojmenované metadata vedle URL a těla zprávy.

HTTP request i response mohou obsahovat sadu hlavičkových polí. Každé má název a hodnotu; názvy jsou v HTTP bez ohledu na velká a malá písmena. V HTTP/1.1 stojí hlavičky mezi startovní řádkou a prázdným řádkem, který odděluje volitelné tělo zprávy. HTTP/2 a HTTP/3 je přenášejí jinou formou, jejich význam ale zůstává součástí HTTP semantiky.

Hlavička není univerzální místo pro libovolná data. Její název a význam určují standard, dokumentovaný kontrakt nebo vědomě navržené rozšíření. Typicky Content-Type říká, zda je tělem JSON, Accept vyjadřuje preferovanou reprezentaci, Authorization nese autentizační údaj a Cache-Control určuje pravidla pro cache.

K čemu se používá

K popisu zprávy, řízení cache i předání bezpečnostního kontextu

Stejný JSON může mít jiný význam podle metody, URI a relevantních hlaviček.

Content-Type a Accept pro typ a dohodu o reprezentaci dat
Authorization, WWW-Authenticate a cookies pro přihlášení a přístup k API
Cache-Control, ETag a Last-Modified pro ukládání a podmíněné načtení odpovědi
Content-Security-Policy, Strict-Transport-Security a Set-Cookie pro bezpečnost prohlížeče
X-Request-ID, traceparent a omezeně Forwarded pro dohledání požadavku přes proxy

Praktický příklad

Webhook s typem obsahu, podpisem a trasováním

Dopravce odešle webhook o změně zásilky. Content-Type říká aplikaci, že má bezpečně zpracovat JSON, podpisová hlavička slouží k ověření integrity podle smluveného postupu a X-Request-ID pomůže dohledat konkrétní doručení. Aplikace ověří podpis nad přesně stanovenými daty; samotný název hlavičky není důkazem původu.

Response 204 sdělí, že server událost přijal, aniž by vracel tělo. Pokud zpracování běží asynchronně, 204 není tvrzení, že zásilka je už promítnutá do všech navazujících systémů.

POST /webhooks/carrier HTTP/1.1
Content-Type: application/json
X-Signature: sha256=<podpis>
X-Request-ID: 01H...

{"shipmentId":"S-42","status":"delivered"}

HTTP/1.1 204 No Content
X-Request-ID: 01H...
Cache-Control: no-store

Jak funguje

Hlavička dostane význam až u správného příjemce

Příjemce vyhodnocuje jen pole, kterým rozumí a která jsou důvěryhodná v daném místě cesty.

Klient sestaví request Přidá například Accept, Content-Type a Authorization. Browser také podle situace posílá cookies či origin.
Proxy provede vlastní pravidla Reverse proxy může některá pole nastavit, odstranit nebo přidat. Forwardované hlavičky z internetu nemají být bez úpravy vydávány za důvěryhodný kontext.
Aplikace validuje kontrakt Zkontroluje očekávaný Content-Type, ověří token a rozhodne, zda konkrétní vlastní hlavička patří k dokumentované verzi API.
Odpověď popíše výsledek Server vrátí status, Content-Type, cache pravidla a případně bezpečnostní či diagnostická pole.
Klient nebo cache je interpretuje Prohlížeč použije bezpečnostní politiku, klient vybere parser JSONu a cache podle pravidel rozhodne o uložení či znovuověření.

Hlavní části a pojmy

Ne každá hlavička se chová stejně na celé cestě.

Rozlišení účelu a důvěryhodnosti pomáhá předcházet chybám v API i proxy konfiguraci.

Request a response fields

Accept nebo Authorization dává smysl v requestu. Content-Type, Cache-Control či Location často popisují response. Některá pole mohou existovat na obou stranách, ale jejich význam se liší.

Reprezentace obsahu

Content-Type určuje media type těla, například application/json. Accept vyjadřuje, co klient umí přijmout; není to příkaz, aby server vždy vyrobil libovolný požadovaný formát.

End-to-end a hop-by-hop

End-to-end pole patří mezi klienta a koncový server i přes prostředníky. Hop-by-hop pole se týkají jednoho spojení a proxy je nepředává jako metadata aplikace. Connection není mechanismus pro přenos vlastního business kontextu.

Autentizace a citlivost

Authorization nebo Cookie mohou obsahovat citlivý údaj. Nemají se zapisovat celé do běžných logů ani přeposílat na cizí doménu při redirectu. Přítomnost hlavičky navíc neznamená, že je token platný.

Vlastní a forwardované hlavičky

Vlastní pole potřebuje stabilní název a dokumentaci; historický prefix X- z něj nedělá bezpečné ani standardní pole. X-Forwarded-For nebo Forwarded lze věřit jen z kontrolovaného proxy řetězce.

Vztah k ostatním pojmům

Hlavičky propojují HTTP zprávu, cache, proxy a bezpečnost.

Žádná z nich sama nenahrazuje serverové rozhodnutí o přístupu nebo stavu dat.

HTTP: Definuje, jak se metadata přenášejí jako součást requestu a response.
HTTP stavový kód: Status shrne výsledek, zatímco hlavičky jej doplní například Location, Retry-After nebo WWW-Authenticate.
CORS: CORS používá response hlavičky pro rozhodnutí prohlížeče, zda JavaScript smí číst cross-origin odpověď.
Content Security Policy: CSP je bezpečnostní politika pro prohlížeč obvykle posílaná HTTP response hlavičkou.

Výhody a omezení

Standardní metadata dávají interoperabilitu, ale vyžadují přesnou odpovědnost.

Přínosy

oddělení metadat od URL a vlastního obsahu response
standardní spolupráce klientů, cache, browserů, proxy a API gateway
možnost řídit typ obsahu, cache, bezpečnostní politiku a dohledatelnost requestu
rozšiřitelný kontrakt bez zásahu do tvaru každého JSON payloadu

Omezení a časté chyby

důvěra v IP, schéma nebo uživatele jen podle klientem poslané hlavičky
přenos tokenu či cookie do logu, analýzy nebo cizího redirectu
nesoulad Content-Type a skutečného těla
použití vlastního pole bez dokumentace, validace a verzování
zaměnění CORS nebo CSP hlavičky za serverovou autorizaci

Kdy dává smysl

Když informace patří ke zprávě, ne do interní logiky URL.

Hlavičky jsou vhodné pro standardní HTTP metadata, například typ obsahu, preferovanou reprezentaci, cache, autentizaci nebo trasování. V integračním API může idempotency key patřit do hlavičky, pokud tak stanoví kontrakt; vlastní business údaj typu cena položky ale obvykle patří do validovaného těla requestu.

Přidání nové hlavičky není náhrada návrhu. Je nutné určit, zda ji klient smí poslat, zda ji proxy předá, jak se validuje, zda může být opakovaná a zda nesmí být logována. U citlivých nebo bezpečnostních hodnot je důležitější zdroj, kterému aplikace důvěřuje, než název pole.

Na co myslet

Každé pole má mít význam, zdroj a bezpečné zacházení.

Rozhraní je čitelnější, když se používají standardní hlavičky a vlastní rozšíření se drží na minimu.

nastavit a validovat Content-Type pro requesty s tělem a odpovědi s daty
maskovat Authorization, Cookie a další tajemství v aplikačních i proxy logách
důvěřovat Forwarded nebo X-Forwarded-* jen známým proxy adresám
dokumentovat vlastní pole, limity jejich délky a chování při chybějící hodnotě
testovat bezpečnostní a cache hlavičky v HTTP integračních testech

Časté otázky

HTTP hlavičky v praxi

Jsou názvy HTTP hlaviček citlivé na velká písmena?

Ne. HTTP pole se porovnávají bez rozlišení velikosti písmen. V HTTP/2 a HTTP/3 je běžné zobrazit je malými písmeny.

Je Content-Type totéž co Accept?

Ne. Content-Type popisuje skutečné tělo zprávy. Accept vyjadřuje, jaké reprezentace klient preferuje nebo umí přijmout.

Může backend věřit X-Forwarded-For?

Pouze pokud request přišel přes známou proxy, která klientem poslanou hodnotu nahradila nebo správně zpracovala. Přímý klient ji může libovolně podvrhnout.

Mám ukládat Authorization do logu pro debugging?

Ne v běžné podobě. Token či cookie je citlivý údaj; pro diagnostiku se používá maskování, request ID a další neinvazivní metadata.

Jak pracuji s API v praxi

HTTP kontrakt držím čitelný i přes proxy a integrační hranice.

Při vývoji API řeším hlavičky, autentizaci, podpisy webhooků, cache i trasování tak, aby klient i provoz věděli, co se s requestem stalo.

Jak pracuji s API a integracemi Nezávazně probrat projekt