API

API je zkratka Application Programming Interface, česky rozhraní pro programování aplikací. Určuje, jak může jeden program používat funkce nebo data jiného programu: jaké operace existují, jaké vstupy přijímají a co vracejí. API může být součástí knihovny, operačního systému i vzdálené služby. Na webu se tím často myslí HTTP API, ale internetové spojení ani JSON nejsou obecnou podmínkou každého API.

Rozhraní je dohoda o chování

Pro využití služby nestačí znát URL. Klient potřebuje vědět, jak vytvořit požadavek, jak se prokázat, jak rozumět odpovědi a co dělat při chybě. Součástí dohody mohou být datové typy, povinná pole, jednotky, časová pásma, stránkování a limity. Pole nazvané count je bez vysvětlení neúplné: může označovat celkový počet položek nebo jen velikost právě vrácené stránky.

API umožňuje oddělit vnitřní provedení služby od způsobu jejího použití. Klient nemá být závislý na tom, v jakých tabulkách poskytovatel data ukládá. To ale neznamená, že se rozhraní nikdy nezmění. Změna významu pole může rozbít integraci, i když název a datový typ zůstanou stejné.

Požadavky a odpovědi přes HTTP

HTTP API používá adresy a metody, například GET pro získání reprezentace prostředku nebo POST pro zpracování předaných dat podle daného rozhraní. Význam operace je potřeba hledat také v dokumentaci služby. POST nemusí vždy vytvářet nový záznam a úspěšný požadavek nemusí vracet JSON.

Následující fiktivní příklad popisuje načtení stavu úlohy. Používá dokumentační doménu example.com; nejde o skutečný endpoint CyberSquatting.cz:

GET /v1/jobs/123 HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 123, "status": "done", "checked": 10}

Klient musí zkontrolovat stavový kód i obsah. HTTP 200 v příkladu říká, že HTTP operace uspěla. Teprve hodnota status podle naší fiktivní dohody oznamuje dokončení úlohy. JSON je formát dat, nikoli potvrzení správnosti výsledku. Pro skutečné použití by dokumentace musela také určit, co přesně znamená deset zkontrolovaných položek.

Ověření klienta a jeho oprávnění

Autentizace zjišťuje identitu klienta, autorizace rozhoduje o povolených operacích. API může využívat klíč, přístupový token nebo jiný mechanismus. Platný token neznamená automatický přístup ke všem účtům a datům. Kontrola oprávnění ke konkrétnímu objektu patří na server, nikoli pouze do uživatelského rozhraní.

U síťového API chrání HTTPS přenos mezi stranami spojení. Nenahrazuje však správu přístupů a nebrání například náhodnému zveřejnění tokenu v logu nebo repozitáři. Způsob předávání přihlašovacích údajů se řídí dokumentací. Vkládání tajných údajů do URL je problematické i kvůli jejich výskytu v historii a záznamech provozu.

Limity, časové chyby a opakování

Odpověď 429 Too Many Requests označuje překročení limitu požadavků. Může obsahovat hlavičku Retry-After s pokynem k čekání. Způsob počítání limitu se liší: podle účtu, tokenu, adresy, konkrétní operace nebo kombinace pravidel. Zvětšení výkonu klienta ani spuštění více workerů samo o sobě nezvyšuje povolenou zátěž služby.

Timeout představuje ještě jiný problém. Klient nemusí vědět, zda server operaci neprovedl, nebo ji provedl a jen se ztratila odpověď. Slepé zopakování vytvoření objednávky či odeslání výsledku tak může způsobit duplicitu. Idempotentní operace má při opakování stejný zamýšlený účinek jako při jednom provedení; neznamená to nutně totožnou odpověď nebo absenci dalších logových záznamů.

Standard HTTP rozlišuje idempotentní metody, například PUT a DELETE. U POST musí možnost bezpečného opakování zajistit konkrétní návrh, například identifikátor operace a kontrola duplicit. Aplikace potřebuje také stanovit dobu čekání, počet pokusů a způsob oznámení trvalé chyby. Ne každé odmítnutí požadavku je dočasný výpadek.

Dokumentace a příklad fronty úloh

OpenAPI je specifikace pro strojově čitelný popis HTTP API. Popis může zachytit operace, parametry, datová schémata i autentizační mechanismy a posloužit při tvorbě dokumentace nebo klientů. OpenAPI není totéž co OpenAI a není podmínkou existence API. Ani korektní schéma nezaručuje věcnou správnost vracených dat.

Na CyberSquatting.cz slouží API jako spojnice mezi centrální frontou a ověřovacími workery. Podle článku z listopadu 2026 si Raspberry Pi vyzvedává dávky a vrací výsledky. Jde o doložený princip aplikace; zdejší modelová URL ani HTTP metody nejsou dokumentací jejího skutečného rozhraní.

Starší zkušenosti s API na 404M ukazují i provozní závislosti: dostupnost dat, autentizaci, kompatibilitu knihoven a změny podmínek třetích stran. Funkční integrace proto potřebuje více než jednorázový úspěšný požadavek. Důležité je poznat chybu, udržet význam dat a mít postup pro změnu rozhraní.