Slovník pojmů

URL

URL dává prohlížeči, klientovi API i serveru společnou adresu zdroje. Jeho jednotlivé části určují protokol, cíl, cestu a případné parametry; zároveň se často objeví v logu, historii a analytice.

Stručná definice

Adresa zdroje, nikoli samotný obsah ani DNS záznam.

URL je běžný typ URI. Zatímco URI je obecný identifikátor zdroje, URL navíc poskytuje mechanismus jeho nalezení, například https. Adresa https://api.example.cz/orders?state=paid#history tedy neurčuje jen název serveru: říká i jakým schématem se připojit, kam poslat HTTP požadavek a jaký kontext má použít klientská aplikace.

URL neobsahuje IP adresu nutně přímo. Jméno hostitele, například api.example.cz, se před síťovým spojením obvykle přeloží přes DNS. Teprve potom klient naváže spojení s konkrétním serverem a pošle HTTP request. DNS, TLS certifikát, reverse proxy a aplikační routa proto spolupracují, ale nejsou stejný pojem.

K čemu se používá

Stálé adresování stránek, API zdrojů a integračních callbacků

Předvídatelná URL je součástí uživatelského rozhraní i technického kontraktu mezi systémy.

adresa veřejné stránky, kategorie, produktu nebo článku, kterou lze sdílet a indexovat
identifikace API zdroje a jeho podzdrojů, například /orders/123/items
filtrování, stránkování nebo řazení čtecího endpointu přes omezené query parametry
callback URL pro OAuth, webhook nebo přesměrování po dokončení platebního procesu
směrování domén a cest přes nginx či jinou HTTP infrastrukturu na správnou aplikaci

Praktický příklad

Čtecí endpoint katalogu bez citlivých parametrů

API katalogu nabízí filtr značky, stránkování a řazení přes jasně povolené query parametry. Cesta určuje zdroj products, query mění čtecí pohled a fragment zde nedává smysl. Aplikace na serveru ověří, že page je celé kladné číslo, že sort patří do whitelistu a že klient nemůže přes URL napsat libovolný databázový výraz.

Přístupový token v ukázce není součást URL: předává se v HTTP Authorization hlavičce. Adresa se tak dá bezpečněji uložit do dokumentace, access logu a sdílet mezi vývojáři bez automatického rozeslání tajemství.

https://api.example.cz/products?brand=acme&page=2&sort=price_desc
\_____/   \____________/ \________________________________________/
 scheme          host                 path a query parametry

Jak funguje

Od adresy v klientovi k HTTP odpovědi

URL propojí identifikaci zdroje s několika samostatnými síťovými kroky.

Parsování URL Klient rozdělí schéma, authority s hostem a portem, cestu, query a fragment. Relativní odkaz může nejdříve vyřešit vůči základní URL dokumentu.
Překlad hostitele DNS resolver vyhledá záznam pro hostitele a podle TTL může použít dříve uloženou odpověď. URL tím získá síťový cíl, ale DNS nerozhoduje o cestě /orders.
Spojení a TLS Schéma https vede klienta k navázání šifrovaného HTTP spojení. Certifikát ověřuje jméno hostitele, ne parametry query nebo business oprávnění.
HTTP request Klient pošle metodu, Host hlavičku, cestu a query na webový server. Ten může URL směrovat na statický soubor, reverse proxy nebo aplikaci.
Práce s fragmentem Část za # slouží zpravidla klientovi, například pro kotvu v dokumentu. Do běžného HTTP requestu se neposílá, takže ji server nemá používat pro autorizaci ani výběr dat.

Části URL

Každý oddělovač má jiný význam.

Správné rozlišení částí URL předchází nefunkčním odkazům, chybné cache i nechtěnému úniku údajů.

Schéma

https určuje použití HTTP přes TLS. Nejde o pouhou kosmetiku: přesměrování mezi http a https, secure cookies i generování absolutních adres musí s protokolem počítat.

Host a port

Host je jméno domény nebo IP adresa, port určuje síťovou službu. DNS řeší jméno hostitele; URL cesta a query nejsou součástí DNS záznamu.

Path

Cesta typicky vybírá stránku nebo API prostředek. Je vhodné ji navrhovat stabilně a čitelně, protože změna může rozbít záložky, integrace i vyhledávače.

Query a kódování

Query nese páry parametrů. Rezervované znaky a data mimo povolenou sadu se zapisují percent-encodingem; pro hodnoty je potřeba používat URL encoder, ne ruční skládání řetězce.

Fragment

Fragment označuje část dokumentu na straně klienta. Není součástí požadavku na server a nemá nést údaje, které musí backend bezpečně zpracovat.

Vztah k ostatním pojmům

URL ukazuje na cíl, DNS jej překládá a HTTP s ním komunikuje.

Rozdělení těchto odpovědností je důležité při diagnostice výpadku i návrhu API.

DNS: Překládá jméno hostitele na síťový cíl nebo deleguje správu domény. Neobsahuje API cesty, query parametry ani obsah URL.
REST API: REST používá URL prostředků, HTTP metody a stavové kódy. URL sama neurčuje, zda operace je RESTful ani jak vypadá odpověď.
OpenAPI: Specifikace popisuje dostupné HTTP cesty, parametry a schémata zpráv. JSON formát či OpenAPI dokument nejsou automaticky součástí URL.
nginx: Webový server rozhodne podle hostitele a cesty, zda odpověď vrátí sám, nebo ji předá aplikaci.

Výhody a omezení

Stabilní adresa je rozhraní, které je potřeba chránit.

Přínosy

jednoznačné sdílení odkazů a API kontraktů
čitelné adresy usnadňují navigaci, debugging i dokumentaci
cesta a query dovolují popsat veřejný čtecí pohled bez vlastního formátu
správně navržená URL podporuje cache, přesměrování i audit provozu

Rizika a chyby

heslo, access token nebo osobní údaj v query se může objevit v historii, logu, refereru či analytice
neomezené query parametry vedou k nejasnému kontraktu, cache fragmentaci nebo injekčním chybám
změna cesty bez redirectu rozbije existující odkazy a integrační klienty
porovnávání URL prostým řetězcem může přehlédnout kódování, pořadí parametrů nebo canonicalizaci

Hranice použití

Do URL patří adresa a omezený kontext, ne důvěrný stav.

Cesta je vhodná pro stabilní identitu prostředku, například /products/123. Query se hodí pro dobrovolné filtry, stránkování a řazení, pokud jsou parametry validované a jejich rozsah je zdokumentovaný. Stav měnící příkazy, velké payloady a citlivé hodnoty patří do těla vhodného HTTP requestu nebo do bezpečného serverového úložiště, ne do volně sdíleného odkazu.

URL může nést veřejný identifikátor objednávky v administraci, ale samotný identifikátor nesmí být jedinou autorizací. Aplikace ověřuje přihlášeného uživatele, tenant a oprávnění na serveru. Odlišné URL pro jazyk, obchod nebo verzi API musí být záměrné a zachycené v cache klíči i dokumentaci.

Na co myslet

Adresy generovat, validovat a logovat s vědomím jejich viditelnosti.

Přehledný návrh URL omezuje citlivý obsah a dává klientům jasný, dlouhodobý kontrakt.

pro externí adresy používat HTTPS a správně generovat schéma za reverse proxy
nevkládat hesla, API klíče, osobní údaje ani dlouhodobé tokeny do query či cesty
parametry URL vytvářet přes standardní encoder a na serveru validovat jejich typ, rozsah i povolené hodnoty
stabilní URL měnit přes zdokumentovanou migraci a vhodný HTTP redirect
odlišit veřejné cacheovatelné query od personalizovaného obsahu a autorizovaných operací
v logu nebo monitoringu citlivé části adres maskovat či neshromažďovat

Časté otázky

Jak URL používat bezpečně a srozumitelně

Je URL totéž co DNS?

Ne. URL popisuje celou adresu zdroje včetně schématu, hostitele a cesty. DNS řeší jen jméno hostitele a jeho síťové záznamy.

Mohu dát token do query parametru?

Pro dlouhodobý nebo citlivý token ne. URL se často ukládá do historie, logů, refereru a analytiky. Autentizace se obvykle předává hlavičkou nebo bezpečnou relací.

Posílá prohlížeč fragment za # na server?

Běžně ne. Fragment interpretuje klient, například pro posun na část dokumentu. Backend jej proto nemůže spolehlivě použít pro rozhodování.

Je URL vždy stejné jako URI?

URL je běžně chápáno jako typ URI, který poskytuje i způsob nalezení zdroje. V praktické webové komunikaci se termíny někdy používají volně, ale URI je obecnější pojem.

Jak navrhuji API v praxi

HTTP kontrakt stavím kolem čitelných adres, oprávnění a předvídatelného chování.

U integračních a e-commerce backendů řeším URL, validaci vstupu, autentizaci i návaznost na veřejnou dokumentaci jako jeden celek.

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