Tato stránka obsahuje dokumentaci a tutoriál k REST API, které zpřístupňuje otevřená data zveřejňovaná sdružením CZ.NIC. Toto API mimo jiné využívají statistické dashboardy.

Pro praktické vyzkoušení níže uvedených příkladů je potřebný nástroj curl.

PostgREST

Data o registru CZ, DNS, MojeID a jiných službách provozovaných sdružením CZ.NIC jsou periodicky stahována z různých zdrojů a ukládána do servisní databáze PostgreSQL. Podrobnosti o metodách sběru dat je možné získat na stránce projektu ADAM.

REST API je pak nad servisní databází generováno automaticky pomocí API serveru PostgREST. Tento poměrně mocný nástroj umožňuje vystavit všechny databázové tabulky a náhledy (views) jako endpointy REST API. Databázový dotaz se všemi svými parametry je pak nutné pro použití přes REST API zakódovat do podoby URL (Uniform Resource Locator). Kvůli tomu se někdy může syntaxe parametrů dotazu v PostgREST zdát poněkud nesrozumitelná. REST API je také nakonec určeno především pro automatizovaný přístup, používaný zejména ve webových aplikacích. V následujících řádcích se ale pokusíme ukázat, že po kratším zacvičení je může stejně dobře používat i běžný smrtelník.

Bázovým URL (base URL) otevřených dat sdružení CZ.NIC je https://stats.nic.cz. Sestava endpointů generovaných pomocí PostgREST je plochá, což znamená, že všechny URL cesty (routes) mají jen jednu komponentu a jsou tedy na stejné úrovni hierarchie. Jinými slovy, všechny URL jsou v tomto obecném tvaru:

https://stats.nic.cz/<endpoint>?<parametry>

přičemž <parametry> jsou nepovinné (spolu s otazníkem).

OpenAPI/Swagger

PostgREST rovněž generuje strojově čitelnou specifikaci celého REST API vyjádřenou pomocí jazyka OpenAPI. Pro člověka je ovšem užitečnější podobou OpenAPI dokumentu tzv. Swagger UI. Toto webové rozhraní poskytuje seznam všech dostupných endpointů spolu s popisem příslušných parametrů dotazu:

Pro lepší přehlednost je soupis endpointů (v současnosti je jich téměř 150) rozdělen do deseti kategorií uvedených v následující tabulce:

Kategorie Obsah
cz statistiky provozu DNS pro doménu .cz
ca statistiky provozu DNS pro doménu .ca
crawler data získaná z DNS crawleru
dns parametry služby DNS (doba odezvy)
domain žebříček domén druhé úrovně pod .cz
fred data z registru CZ
fredlog statistiky operací v registru CZ
internal interní endpointy (nejsou určeny pro veřejné použití)
mojeid statistiky identitní služby MojeID
odvr statistiky provozu DNS pro veřejný resolver ODVR

Přístup k endpointům označeným ikonou visacího zámku je vyhrazen pro přihlášené a autorizované uživatele. Ve webovém rozhraní Swagger lze s těmito endpointy pracovat, pokud se uživatel buď přihlásí do statistických dashboardů v jiném okně nebo záložce prohlížeče, anebo klikne na ikonu zámku a zadá platný API token.

Praktický příklad

Představme si, že máme za úkol udělat výzkum aktuálních trendů na českém trhu s doménami. Potřebujeme pro něj znát počty domén zanesených do registru CZ jednotlivými registrátory, řekněme za období od 1. ledna 2022. Jak taková data získáme?

Podíváme-li se do tabulky v předchozím oddílu, můžeme odhadnout, že data týkající se registru najdeme v kategorii fred (FRED je totiž software, který CZ.NIC vyvinul a používá ke správě registru CZ). V této kategorii vypadá obzvlášť slibně endpoint /fred_domains_by_registrar 1

Kliknutím na jméno endpointu ve webovém rozhraní Swagger dostaneme podrobnější náhled, který ukazuje všechny dotazové parametry platné pro tento endpoint, jak je ukázáno v tomto (neúplném) snímku obrazovky:

Dotazové parametry bodou podrobněji popsány níže. Některé z nich se vztahují k jednotlivým polím (databázovým sloupcům) zdroje reprezentovaného daným endpointem, další jsou pak obecné a slouží specifickým účelům v API PostgREST.

Prozatím se soustřeďme na jinou užitečnou vlastnost rozhraní Swagger, totiž na možnost přímého dotazování pomocí REST API. Po kliknutí na tlačítko Try it out je možné vyplnit hodnoty parametrů dotazu ve formuláři endpointu, a dotaz se pak odešle kliknutím na tlačítko Execute. Takto můžeme snadno získat základní představu o obsahu endpointu.

Než to však opravdu vyzkoušíte a nepředloženě způsobíte zamrznutí okna prohlížeče, je užitečné se dozvědět o dotazovém parametru limit, poněvadž prostředí webového prohlížeče není úplně vhodné pro výpočetně náročné úlohy, jako je stahování a zobrazování obřích objemů dat. Je proto celkem moudré nastavit parametr limit (nachází se ve spodní části webového formuláře) na rozumně nízké číslo, například 10.

Po provedení dotazu zobrazí prohlížeč výsledná data a hlavičky HTTP odpovědi, ale také ukáže URL právě dokončeného dotazu, který byl z webového formuláře sestaven, a pro větší pohodlí uživatele i kompletní příkaz využívající nástroj curl, který se může použít z příkazové řádky.

Parametry dotazu

Jak jsme už prozradili, jedna část parametrů dotazu se váže ke konkrétnímu endpointu (respektive jemu odpovídající tabulce či náhledu v databázi). Mohou se požít k nastavení rozsahu výsledných dat (záznamů i polí).

Filtrování záznamů

Pomocí speciální syntaxe je možné v parametrech dotazu specifikovat podmínky na hodnoty polí/sloupců. Záznamy/řádky, které tyto podmínky nesplňují, jsou pak z výstupních dat vynechány. Nejčastěji se požívají následující relační operátory:

Operátor Význam
eq je rovno
neq není rovno
gt větší než
gte větší nebo rovno
lt menší než
lte menší nebo rovno

Tak například můžeme zkusit poslat dotaz na náš oblíbený endpoint /fred_domains_by_registrar, ale jen pro data týkající se domény cz (jinak bychom totiž dostali také data pro ENUM doménu 0.2.4.e164.arpa). Toho dosáhneme následovně za pomoci operátoru eq:

$ curl -s "https://stats.nic.cz:443/fred_domains_by_registrar?zone=eq.cz&limit=10"
[{"ts":"2020-05-22T12:00:00+00:00","registrar_id":"REG-1API","domains":11771,"zone":"cz"}, 
 {"ts":"2020-05-22T12:00:00+00:00","registrar_id":"REG-ACTIVE24","domains":175663,"zone":"cz"}, 
 {"ts":"2020-05-22T12:00:00+00:00","registrar_id":"REG-AERO-TRIP","domains":2227,"zone":"cz"}, 
 {"ts":"2020-05-22T12:00:00+00:00","registrar_id":"REG-ASCIO","domains":2783,"zone":"cz"}, 
 {"ts":"2020-05-22T12:00:00+00:00","registrar_id":"REG-ASPONE","domains":2091,"zone":"cz"}, 
 {"ts":"2020-05-22T12:00:00+00:00","registrar_id":"REG-BANAN","domains":5433,"zone":"cz"}, 
 {"ts":"2020-05-22T12:00:00+00:00","registrar_id":"REG-CORE","domains":438,"zone":"cz"}, 
 {"ts":"2020-05-22T12:00:00+00:00","registrar_id":"REG-CT","domains":924,"zone":"cz"}, 
 {"ts":"2020-05-22T12:00:00+00:00","registrar_id":"REG-CZNIC","domains":229,"zone":"cz"}, 
 {"ts":"2020-05-22T12:00:00+00:00","registrar_id":"REG-DIAL-TEL","domains":717,"zone":"cz"}]

Tohle je celkem srozumitelné: chceme jen záznamy, v nichž je hodnota pole zone rovna cz. I zde jsme použili parametr limit, aby nebyl výsledek moc dlouhý (ale klidně ho odstraňte, pokud příkaz spouštíte sami z příkazové řádky). Všimněte si zde také, že parametry dotazu, pokud je jich více, jsou v souladu s pravidly pro vytváření URL od sebe odděleny znakem &.

Mimochodem, každé URL, které předáváme na příkazové řádce nástroji curl, funguje prakticky úplně stejně i ve webovém prohlížeči:

Další úkol je už o něco složitější: chceme pouze data počínaje od 1. ledna 2022. Toho můžeme dosáhnout omezením hodnoty sloupce ts (time stamp) tak, aby byla větší nebo rovna (gte) tomuto datu:

$ curl -s "https://stats.nic.cz:443/fred_domains_by_registrar?ts=gte.2022-01-01&zone=eq.cz&limit=10"
[{"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-1API","domains":20042,"zone":"cz"}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-ACTIVE24","domains":186744,"zone":"cz"}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-AERO-TRIP","domains":2201,"zone":"cz"}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-ASCIO","domains":4876,"zone":"cz"}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-ASPONE","domains":1923,"zone":"cz"}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-BANAN","domains":4589,"zone":"cz"}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-CORE","domains":489,"zone":"cz"}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-CT","domains":855,"zone":"cz"}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-CZNIC","domains":249,"zone":"cz"}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-DIAL-TEL","domains":740,"zone":"cz"}]

PostgREST má několik dalších operátorů, které můžeme využít ke specifikaci podmínek na hodnoty polí. Navíc jsou k dispozici logické operátory (and, or a not), s jejichž pomocí lze podmínky různými způsoby kombinovat. Pokud se chcete dozvědět všechny podrobnosti, přečtěte si prosím dokumentaci.

Výběr polí

Nezávisle na filtrování záznamů/řádků umožňuje PostgREST také vybírat výstupní pole/sloupce pomocí dotazového parametru select.

V předchozím oddílu jsme omezili výstupní záznamy jenom na ty, které mají ve svém poli zone hodnotu cz. Tím pádem toto pole přestává být zajímavé a můžeme ho ve výstupu potlačit:

$ curl -s "https://stats.nic.cz:443/fred_domains_by_registrar?select=ts,registrar_id,domains&ts=gte.2022-01-01&zone=eq.cz&limit=10"
[{"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-1API","domains":20042}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-ACTIVE24","domains":186744}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-AERO-TRIP","domains":2201}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-ASCIO","domains":4876}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-ASPONE","domains":1923}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-BANAN","domains":4589}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-CORE","domains":489}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-CT","domains":855}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-CZNIC","domains":249}, 
 {"ts":"2022-01-01T23:59:59+00:00","registrar_id":"REG-DIAL-TEL","domains":740}]

Všimněte si, že není možné zadat „vyber všechna pole kromě …“, ale musíme všechna ta zbývající pole pečlivě vypsat.

Třídění záznamů

Výstupní záznamy jsou standardně řazeny podle interních pravidel databáze PostgreSQL. Jiné uspořádání (případně i podle hodnot více polí) můžeme získat pomocí dotazového parametru order.

Například, pokud chceme výstup domén podle registrátorů uspořádat primárně podle identifikátoru registrátora ve vzestupném pořadí (asc, ascending), a sekundárně pak ještě podle časové značky v sestupném pořadí (desc, descending), stačí dotaz upravit takto:

$ curl -s "https://stats.nic.cz:443/fred_domains_by_registrar?select=ts,registrar_id,domains&ts=gte.2022-01-01&zone=eq.cz&order=registrar_id.asc,ts.desc&limit=10"
[{"ts":"2025-04-01T23:59:59+00:00","registrar_id":"REG-1API","domains":22324}, 
 {"ts":"2025-03-31T23:59:59+00:00","registrar_id":"REG-1API","domains":22369}, 
 {"ts":"2025-03-30T23:59:59+00:00","registrar_id":"REG-1API","domains":22399}, 
 {"ts":"2025-03-29T23:59:59+00:00","registrar_id":"REG-1API","domains":22442}, 
 {"ts":"2025-03-28T23:59:59+00:00","registrar_id":"REG-1API","domains":22471}, 
 {"ts":"2025-03-27T23:59:59+00:00","registrar_id":"REG-1API","domains":22535}, 
 {"ts":"2025-03-26T23:59:59+00:00","registrar_id":"REG-1API","domains":22532}, 
 {"ts":"2025-03-25T23:59:59+00:00","registrar_id":"REG-1API","domains":22598}, 
 {"ts":"2025-03-24T23:59:59+00:00","registrar_id":"REG-1API","domains":22633}, 
 {"ts":"2025-03-23T23:59:59+00:00","registrar_id":"REG-1API","domains":22661}]

Naše URL už začíná být pěkně složité, že?

Výstupní formáty

PostgREST používá pro výstup záznamů standardně formát JSON. Někdy se více hodí CSV formát (comma-separated values), třeba pro použití v tabulkovém softwaru. Výstupní formát je možné změnit pomocí dotazového parametru _accept (povšimněte si podtržítka na začátku):

$ curl -s "https://stats.nic.cz:443/fred_domains_by_registrar?select=ts,registrar_id,domains&ts=gte.2022-01-01&zone=eq.cz&order=registrar_id.asc,ts.desc&_accept=text/csv&limit=10"
ts,registrar_id,domains
"2025-04-01 23:59:59+00",REG-1API,22324
"2025-03-31 23:59:59+00",REG-1API,22369
"2025-03-30 23:59:59+00",REG-1API,22399
"2025-03-29 23:59:59+00",REG-1API,22442
"2025-03-28 23:59:59+00",REG-1API,22471
"2025-03-27 23:59:59+00",REG-1API,22535
"2025-03-26 23:59:59+00",REG-1API,22532
"2025-03-25 23:59:59+00",REG-1API,22598
"2025-03-24 23:59:59+00",REG-1API,22633
"2025-03-23 23:59:59+00",REG-1API,22661

API tokeny

Jak jsme se už zmínili, přístup k některým endpointům v REST API je omezen na autorizované uživatele, a vyžaduje tedy předchozí autentizaci. Pro strojový přístup, například z webových aplikací, je nejvhodnější pro autentizaci použít API tokeny. Tato metoda se také někdy nazývá autentizace držitele (bearer authentication).

API token je náhodný řetězec čítající 36 znaků (hexadecimálních číslic a spojovníků). Když takový token vložíme do HTTP hlavičky Authorization, můžeme jeho prostřednictvím přistupovat k chráněným zdrojům, pro které byl token vytvořen (viz níže).

Použití API tokenu s nástrojem curl vypadá takto:

$ curl -s -H "Authorization: Bearer f85db341-5069-4663-a16c-d79abf86feb8" "https://stats.nic.cz/ca_qps_total_1h?limit=10"
[{"ts":"2020-08-03T22:00:00+00:00","qps":2871.3975}, 
 {"ts":"2020-08-03T23:00:00+00:00","qps":2854.339}, 
 {"ts":"2020-08-04T00:00:00+00:00","qps":3084.3193}, 
 {"ts":"2020-08-04T01:00:00+00:00","qps":3247.8638}, 
 {"ts":"2020-08-04T02:00:00+00:00","qps":2934.327}, 
 {"ts":"2020-08-04T03:00:00+00:00","qps":2954.8071}, 
 {"ts":"2020-08-04T04:00:00+00:00","qps":3129.4106}, 
 {"ts":"2020-08-04T05:00:00+00:00","qps":3029.339}, 
 {"ts":"2020-08-04T06:00:00+00:00","qps":2967.8}, 
 {"ts":"2020-08-04T07:00:00+00:00","qps":2882.29}]

Správa tokenů

Každý uživatel, který má přístup k některým chráněným zdrojům v REST API, může po přihlášení vytvářet, prohlížet a odvolávat API tokeny. K těmto operacím se dostane přes položku Spravovat tokeny v uživatelském menu.

Při vytváření nového tokenu je třeba ve formuláři zadat následující údaje:

  • Token name – libovolný řetězec, který bude sloužit k identifikaci tokenu.
  • Authorized paths – výběr cest (zdrojů) v API, pro něž může být token použit. Na začátku je zaškrtnuté políčko Access to all paths, což znamená, že je povolen přístup ke všem zdrojům, pro něž je uživatel autorizován. Vypnutím této volby se dostaneme k seznamu těchto zdrojů, a v něm je pak můžeme vybírat jednotlivě.
  • Expiration date/time – datum a volitelně také čas, kdy skončí platnost tokenu. Implicitně mají tokeny neomezenou platnost.

Po kliknutí na tlačítko Create a new token by se měl nový token objevit v seznamu nahoře na stránce:

Token je možné odvolat (revokovat) kliknutím na tlačítko Revoke.

  1. Jiný endpoint podobného jména – /fred_domains_by_registrar_latest – má jen nejčerstvější hodnoty, my ale, jak víme, potřebujeme data od začátku roku.↩︎