Slovník pojmů

Query string

Query string přidává k URL volitelné parametry, například pro filtrování, stránkování a řazení. Je součástí adresy, a proto se může objevit v historii, logu, analytice i refereru.

Stručná definice

Volitelný kontext URL, ne tajný kanál ani SQL dotaz.

Query string začíná otazníkem a jednotlivé parametry se běžně oddělují znakem &. V adrese https://api.example.cz/orders?status=paid&page=2 je cesta /orders a dvojice status=paid a page=2 tvoří query string. Každý parametr má název a případně hodnotu; jejich přesný význam určuje konkrétní web nebo API kontrakt.

Parametry musí být URL kódované a na serveru převáděné z textu na očekávané typy. To, že klient poslal page=2 nebo sort=-createdAt, neznamená, že mu server musí důvěřovat. Aplikace kontroluje povolené názvy, hodnoty, rozsahy, tenant a oprávnění stejně jako u jiného vstupu.

Jaký problém řeší

Sdílitelný čtecí pohled bez vytváření nové cesty pro každou variantu.

Query parametry se hodí pro omezený a dokumentovaný kontext, který uživatel může uložit nebo poslat dál.

filtrování seznamu objednávek podle stavu, období nebo zákazníka
stránkování a velikost stránky v administraci nebo veřejném katalogu
řazení podle předem povolených sloupců a směru
vyhledávací výraz, pokud se nejedná o citlivé údaje
volitelná podoba čtecí odpovědi API, pokud to kontrakt výslovně podporuje

Praktický příklad

Filtrování objednávek s omezeným řazením.

Administrace zobrazuje pouze objednávky ve stavu paid, druhou stránku výsledků a řazení od nejnovějších. Server nebere parametr sort jako SQL výraz: převede jej na jednu z předem povolených variant. Stejně validuje číslo stránky a aktuální tenant načte z ověřené identity, ne z URL.

Příklad neobsahuje token ani e-mail zákazníka. Pokud uživatel URL uloží do záložek nebo se objeví v logu reverse proxy, zůstane v ní jen neškodný filtr.

URL

https://api.example.cz/orders?status=paid&page=2&sort=-createdAt

status = paid
page   = 2
sort   = -createdAt

Jak funguje

Od URL parametru k bezpečnému filtru v aplikaci.

Klient zapisuje text do URL, server z něj teprve vytváří ověřený aplikační vstup.

Klient sestaví URL Hodnoty se kódují standardním URL encoderem. Ruční spojování řetězců často chybně pracuje s mezerami, ampersandem nebo znaky mimo ASCII.
Prohlížeč nebo API klient pošle request Query je součástí request targetu. Fragment za znakem # se do běžného HTTP requestu neposílá, proto není query stringem.
Framework parametry rozparsuje Aplikace získá textové hodnoty a musí rozhodnout, zda chybějící, prázdná či opakovaná hodnota dává v jejím kontraktu smysl.
Validace vytvoří povolený filtr page se převede na kladné celé číslo, status se ověří proti seznamu stavů a sort se vybere z whitelistu, nikoli z libovolného SQL fragmentu.
Odpověď zachová srozumitelný kontrakt Server vrátí výsledky, případně bezpečnou validační chybu. Cache a canonical URL musí počítat s tím, které parametry skutečně mění obsah.

Důležité pojmy

Název, hodnota, kódování a opakování parametrů.

URL standard upravuje syntaxi URL, ale význam parametrů vždy náleží aplikaci nebo API.

Cesta a query

Cesta typicky označuje prostředek, například /orders. Query mění čtecí pohled, například ?status=paid. Hranice není absolutní, ale má být stabilní a zdokumentovaná.

URL encoding

Znaky se zvláštním významem a data mimo bezpečnou znakovou sadu potřebují percent-encoding. Kódování není sanitizace ani validace významu hodnoty.

Opakovaný parametr

Adresy jako ?tag=php&tag=api jsou možné, ale různé frameworky mohou opakování interpretovat odlišně. Kontrakt má říct, zda jde o seznam, chybu nebo poslední hodnotu.

Prázdná a chybějící hodnota

q=, q a úplně chybějící q nemusí znamenat totéž. Aplikace musí odlišit výchozí filtr, požadavek na prázdnou hodnotu a neplatný vstup.

Query a cache

Parametry, které mění odpověď, patří do cache klíče. Naopak sledovací parametry často nemají vytvářet duplicitní kanonické stránky ani rozbíjet cache.

Vztah k podobným pojmům

Query string je část URL, ne HTTP hlavička, tělo requestu ani databázový dotaz.

Přesné rozlišení snižuje únik citlivých údajů i riziko injekčního zpracování vstupu.

URL: URL zahrnuje schéma, hostitele, cestu a případně query i fragment. Query string je pouze jedna jeho volitelná část.
HTTP hlavička: Hlavičky nesou metadata zprávy, například Authorization nebo Accept. Query je viditelná část adresy a nemá sloužit jako náhrada citlivé hlavičky.
HTTP tělo: Tělo je vhodné pro větší či stav měnící payload. Query se nepoužívá jako univerzální přenos libovolné struktury nebo hesla.
SQL injection: Parametr URL je nedůvěryhodný vstup. Po validaci se hodnota předává do parametrizovaného SQL, zatímco názvy řazení se řeší whitelistem.

Výhody a omezení

Čitelné adresy za cenu omezené viditelnosti a délky.

Přínosy

lze sdílet a uložit konkrétní filtr nebo stránku seznamu
funguje přirozeně pro navigaci, cache a historii prohlížeče
čtecí API má jasný, dokumentovatelný způsob filtrování a stránkování
parametry lze snadno kombinovat, pokud jejich pravidla zůstávají jednoduchá

Omezení a chyby

citlivá data mohou uniknout do historie, access logu, analytiky či Referer hlavičky
velmi dlouhá URL naráží na praktické limity klientů, proxy a serverů
neomezené parametry vedou k nejasnému kontraktu, cache fragmentaci a složitým dotazům
přímé vkládání parametrů do SQL nebo příkazů otevírá injekční riziko
query nemá být jediným zdrojem oprávněného tenant kontextu

Praktické použití

Používat pro popis pohledu, ne pro důvěrný stav nebo velký formulář.

Seznam objednávek může rozumně používat status, page a sort. Endpoint vytvoření objednávky naopak přijme data v těle POST requestu, protože jde o stav měnící operaci s větší strukturou a citlivějším kontextem. HTTP metoda sama sice nezaručuje správné chování aplikace, ale návrh URL má tuto sémantiku podporovat.

U vyhledávání je vhodné stanovit maximální délku, normalizovat prázdné hodnoty a rozlišit veřejný filtr od personalizovaného pohledu. Token, heslo, e-mail v odkazové kampani nebo session identifikátor do query nepatří: adresa je snáze viditelná a kopírovatelná než bezpečná HTTP hlavička či serverová session.

Na co myslet

Parametry explicitně popsat, vytvořit bezpečně a přísně validovat.

Každý parametr je vstup z nedůvěryhodného klienta a zároveň součást veřejného rozhraní.

používat srozumitelná jména parametrů a dokumentovat jejich typ, výchozí hodnotu a limit
hodnoty URL generovat standardním encoderem a nikdy je neslepovat jako neověřený řetězec
validovat čísla, data, enum hodnoty, opakování i maximální délku před použitím v aplikaci
pro dynamické řazení vybírat sloupec a směr z whitelistu, neparametrizovatelné identifikátory nepřebírat od klienta
neumísťovat do adresy tokeny, hesla, session ID ani nadbytečné osobní údaje
zvážit canonicalizaci a cache pravidla, pokud více variant adresy vrací stejný obsah

Časté otázky

Query parametry v praxi

Je query string součástí URL?

Ano. Začíná obvykle otazníkem a obsahuje parametry. Není to ale celá URL; ta zahrnuje také schéma, hostitele, cestu a případně fragment.

Posílá se fragment za # na server?

Běžně ne. Fragment zpracovává klient, například pro posun na část stránky. Query string se naopak do HTTP requestu posílá.

Mohu do query dát access token?

Pro citlivý nebo dlouhodobý token ne. URL se může objevit v historii, logu a refereru. Pro oprávnění je vhodnější bezpečná hlavička nebo serverová session.

Je pořadí query parametrů důležité?

Nemělo by být bez jasně popsaného důvodu. Aplikace má určit, jak pracuje s opakováním a canonicalizací, protože prosté porovnání URL řetězcem bývá zavádějící.

Jak navrhuji API v praxi

Adresy, filtry a oprávnění propojuji do jednoho čitelného kontraktu.

U integračních a e-commerce backendů řeším stabilní URL, validaci vstupů, bezpečné stránkování i předvídatelné chybové odpovědi.

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