API a FastAPI jednoduchými slovy

API je způsob, jakým se programy obracejí jeden na druhý. Jeden žádá, druhý odpovídá. Podíváme se na příkladu tržiště, z čeho se skládá požadavek, jak číst JSON odpověď a co zkontrolovat, když Claude Code připojuje externí zdroj dat. Na konci si krátce ujasníme, kde se tu můžete setkat s FastAPI.

Co je API jednoduchými slovy

API (Application Programming Interface) je programové rozhraní. Definuje dostupné operace a pravidla pro jejich použití. API mají nejen jednotlivé aplikace, ale i knihovny, operační systém a prohlížeč. Program přes něj může požádat jiný program nebo jeho část, aby něco udělal, a dostat výsledek. Zde budeme mluvit především o síťových API, ke kterým se přistupuje přes adresu.

Představte si restauraci. Jako zákazník nechodíte do kuchyně a nevysvětlujete kuchaři, jak má vařit. Řeknete číšníkovi, co si z menu přejete, on předá objednávku do kuchyně a přinese vám hotové jídlo. API je jako číšník. Klientský program přes něj objednává a kuchyně (jiný program) objednávku vyřizuje. Nemusíte vědět, jak to všechno uvnitř funguje - stačí znát menu a vědět, o co lze požádat a co přijde jako odpověď.

API je v podstatě smlouva: "obracet se na mě můžete takhle a v odpovědi vám vrátím takovýhle výsledek".

Existuje i krátké vtipné video v angličtině - "How API work". Je to ilustrace k téže myšlence, nikoli vysvětlení tématu. Všechno potřebné najdete v textu níže.

Požadavek a odpověď na příkladu tržiště

Představte si tržiště, kam dodavatel vkládá produkty ze svého programu. Přesouvat tisíce položek pomocí tlačítek na webu by bylo nepohodlné, takže tržiště poskytuje programové operace API. Například POST /products přidá produkt a GET /reports vrátí report.

Adresa dostupné operace se nazývá endpoint. Chcete-li porozumět požadavku, podívejte se na adresu i na HTTP metodu. GET /products a POST /products mohou dělat různé věci. GET se obvykle používá pro čtení, POST pro odesílání dat ke zpracování.

Data se často odesílají ve formátu JSON. Složené závorky uzavírají pole objektu, řetězce se zapisují v uvozovkách a seznam objektů v hranatých závorkách:

{
  "name": "Stolní lampa",
  "price": 15000,
  "count": 350
}

Klient zašle požadavek, server jej zpracuje a vrátí odpověď. Níže je zkrácené schéma výměny, ne celý HTTP paket:

POST /products
{ "name": "Stolní lampa", "price": 15000, "count": 350 }

201 Created
{ "id": 4567, "status": "added" }

201 Created je status odpovědi a JSON pod ním je tělo s výsledkem. U skutečného API dokumentace uvádí endpoint, metodu, povinné parametry, hlavičky, podobu odpovědi a možné chyby. Bezpečnější je začít jedním testovacím objektem, ne celou sadou dat.

Frontend, backend a API mezi nimi

API neslouží jen k propojení různých aplikací. Často se i jedna aplikace sama skládá ze dvou programů a ty spolu také komunikují přes API.

Frontend je část aplikace, se kterou pracujete v prohlížeči. Patří sem tlačítka, obrázky, menu, formuláře a chování stránky. Jeho programová logika se obvykle píše v jazyce JavaScript. Může sám provádět složité výpočty i se obracet na server, když jsou potřeba data nebo akce na straně služby.

Backend je serverová část aplikace. Zpracovává platby, ukládá objednávky, ověřuje přístup a vyhledává produkty. Během vývoje může server běžet na vašem počítači, po zveřejnění - na hostingu. Uživatel nedostane jeho zdrojový kód spolu se stránkou. Prohlížeč dostane odpovědi na požadavky.

Jak spolu komunikují? Přes stejné API. Backend poskytuje endpointy nejen externím dodavatelům, ale i svému vlastnímu frontendu:

• otevřete stránku - frontend zavolá endpoint /products/list, backend vrátí seznam produktů, frontend je pěkně vykreslí;
• kliknete na "koupit" - frontend pošle data na endpoint /orders, backend vytvoří objednávku.

Přes API tedy mohou komunikovat jak různé aplikace, tak i části jedné aplikace. V tomto schématu prohlížeč zašle požadavek, backend pracuje s daty a vrací výsledek. Databáze nemusí být přímo dostupná prohlížeči.

Požadavek z prohlížeče

Výše jsme říkali, že frontend "volá endpoint" backendu. Podívejme se, jak to vypadá v kódu. V prohlížeči je k tomu vestavěná funkce fetch. Zašle HTTP požadavek na danou adresu a vrátí odpověď. Tělo odpovědi obvykle přichází v JSON a na objekt se převede metodou .json().

Vezměme si číselník národních prostředí (locale) - kombinací jazyka a regionálních nastavení. Předpokládejme, že backend už umí vracet seznam na adrese /locales a frontend ho má zobrazit. Například server vrátí:

[
  { "code": "en-GB", "language": "English", "country": "United Kingdom" },
  { "code": "de-DE", "language": "Deutsch", "country": "Germany" }
]

Jak přichází odpověď

Fragment níže běží uvnitř asynchronní obslužné funkce stránky. Data získá; vykreslení tabulky tu ukázané není.

const res = await fetch("/locales");
if (!res.ok) {
  throw new Error(`HTTP ${res.status}`);
}
const locales = await res.json();
// Nyní locales obsahuje data pro tabulku

Zkontrolujeme res.ok před čtením dat. HTTP chyba jako 404 nebo 500 sama o sobě nezpůsobí, že fetch skončí výjimkou. Zvlášť se může stát, že se síťový požadavek vůbec neuskuteční nebo že se JSON nepodaří zpracovat. Kód stránky by měl chybu z takového fragmentu zachytit a zobrazit srozumitelnou zprávu. Jde o různé příčiny, i když uživatel ve všech případech data nedostal. Podrobněji v průvodci MDN k fetch.

Zde je pár věcí, které se snadno přehlédnou:

• standardně fetch provádí GET - požadavek na získání dat. Jiné operace se zadávají metodou; například naše tržiště přijímá nový produkt přes POST;
• adresa /locales je relativní. Na běžné HTTP stránce míří na kořen stejného origin. Origin je dán schématem, hostitelem a portem; server musí mít takovou trasu;
• fetch a .json() nevracejí výsledek hned, takže se před nimi píše await - "počkej na odpověď".

Pokud otevřete HTML jako soubor přes file://, zápis /locales se nestane adresou vašeho HTTP serveru. V tomto příkladu se stránka otevírá přes server, na kterém je implementována trasa. Samotný soubor HTML takovou trasu nevytváří.

Frontend a API se mohou nacházet na různých origin. Potom musí server API povolit potřebný přístup přes CORS, aby si prohlížeč přečetl odpověď. Jedná se o mechanismus přístupu mezi weby, nikoli o název jakékoli síťové chyby. Umístění stránky a API na stejný origin zjednoduší příklad, ale není povinné pro všechny aplikace. Detaily jsou v popisu CORS na MDN.

Kdo odpovídá prohlížeči

Kdo odpovídá na fetch("/locales")? Backend, a ten nemusí být napsaný v Pythonu s FastAPI. API je domluva mezi programy, ne konkrétní jazyk. Stejný endpoint se dá napsat v Node.js, Go nebo Javě. Například v obsluze serveru v Node.js můžete vrátit připravené pole locales. Níže je jen fragment obsluhy, ne hotový server:

// req a res obdrží obsluha, locales se připraví předem
if (req.method === "GET" && req.url === "/locales") {
  res.statusCode = 200;
  res.setHeader("Content-Type", "application/json; charset=utf-8");
  res.end(JSON.stringify(locales));
}

Zvenčí je to stále stejný HTTP požadavek GET /locales a v odpovědi status 200 a JSON. Frontend nemusí vědět, na čem je backend napsán. Potřebuje adresu, pravidla požadavku a formát odpovědi.

Jaké jsou typy API

API je praktické dělit podle dvou kritérií:

• místní a síťová - například API knihovny se volá z kódu programu, zatímco k síťovému API se přistupuje přes síť. Síť může být i vnitřní, bez otevřeného internetu;
• veřejná a vnitřní - veřejná jsou určena pro externí vývojáře, vnitřní propojují části systému. I veřejné API může vyžadovat registraci, platbu a oprávnění.

Webové API často používají HTTP - protokol pro požadavky a odpovědi. REST, se kterým se v dokumentaci setkáte, popisuje přístup k návrhu API; ne každé HTTP API automaticky odpovídá REST. Zatím je užitečnější naučit se číst stavový kód v odpovědi:

• 200 - všechno je v pořádku;
• 201 - vytvořeno (např. nový objekt po POST);
• 404 - nenalezeno;
• 401 - požadavek neobsahuje vhodné autentizační údaje;
• 429 - příliš mnoho požadavků;
• 500 - vnitřní chyba serveru.

Nyní se nemusíte hluboko zabývat těmito detaily. Důležité je pochopit samotnou myšlenku výměny požadavků a odpovědí. Prozatím je to dost.

Proč služba potřebuje přístupový klíč

Mnoho služeb nejdřív požádá, abyste získali API klíč - řetězec spojený s vaším účtem nebo projektem. Přenáší se tak, jak je uvedeno v dokumentaci, často v hlavičce požadavku. Služba ověří přístup a může sledovat, kolik požadavků jste poslali. V jiných integracích se setkáte se slovem token. Má podobný účel, ale způsob získání, doba platnosti a práva se mohou lišit.

Bez vhodného přístupu se požadavek nevykoná; například server může odpovědět 401. Překročení frekvence požadavků se často značí kódem 429. Přesný význam odpovědi a povolené limity najdete v dokumentaci konkrétní služby. Existují také otevřené zdroje, které klíč vůbec nepotřebují.

Kde hledat hotové API

Přes API se do aplikací vkládají mapy, počasí, platby a doručování. Otevřená dokumentace pomáhá pochopit možnosti služby ještě před připojením. Nejlépe je začít od samotného úkolu. Ujasněte si, jaká data potřebujete, jak často by se měla aktualizovat a co s nimi budete dělat.

Pro hledání je vhodné se podívat na Postman Public API Network, katalog API a příkladů požadavků. Nalezený příklad je jen výchozím bodem. Adresu, formát, přístup a omezení stejně ověřte v oficiální dokumentaci vlastníka služby.

Kde se FastAPI objevuje

FastAPI je jeden z frameworků pro vytváření API a webových serverů v Pythonu. Může propojit endpoint s vaším serverovým kódem, přijmout požadavek a vrátit JSON odpověď. FastAPI potřebujete, když vytváříte svůj vlastní Python backend; abyste mohli používat hotové API, není nutné jej studovat. Na úrovni 7 stačí název poznat a rozumět této hranici.

Jak to funguje s Claude Code

S těmito pojmy se práce agenta hodnotí snáz. Může si přečíst dokumentaci cizího API, napsat klientský požadavek nebo vytvořit vaše API na FastAPI. Pro vás je důležité vidět konkrétní cestu od požadavku k datům na stránce. Kdo posílá požadavek, kdo odpovídá a jak se odpověď zpracuje?

Například pro radar zemětřesení existuje veřejný GeoJSON feed USGS. Adresa seznamu za poslední hodinu:

GET https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson

Níže je malý učební příklad struktury odpovědi, s vymyšlenou událostí a zredukovanou sadou polí. Toto nejsou aktuální data USGS:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "mag": 4.2, "place": "Ukázkové místo" },
      "geometry": { "type": "Point", "coordinates": [-122.5, 38.0, 8.0] }
    }
  ]
}

V features je pole událostí. Cesta features[0].properties.mag vede k magnitudě první události. Index 0 znamená první prvek pole. Souřadnice jdou v pořadí "zeměpisná délka, šířka, hloubka v kilometrech". Agent může použít magnitudu pro velikost bodu a souřadnice pro jeho polohu. Pokud je pole prázdné, první prvek neexistuje; pokud je magnituda null, je to neznámá hodnota, nikoli nulová síla události.

Zbývá se rozhodnout, co se má zobrazit po požadavku:

Během provádění požadavku může stránka zobrazit indikátor načítání. Pro ověření různých výsledků je vhodné použít testovací odpovědi. Nebudete tak muset čekat na skutečný výpadek služby nebo nové zemětřesení.

Úkol pro Claude Code teď může znít takto:

Připoj ke stránce data z uvedeného API.
Nejdřív zkontroluj oficiální dokumentaci: adresa, metoda,
formát odpovědi a podmínky přístupu. Ukaž, která pole používáš.
Počítej s indikátorem načítání, prázdným seznamem a chybou aktualizace.
Pokud po selhání používáš stará data, označ to na stránce.
Neumisťuj tajný klíč do kódu klienta.
Zkontroluj výsledek a řekni, jaké stavy se podařilo ověřit.

Po práci se podívejte na samotný požadavek a výsledek ověření, ne jen na hotový obrázek. Zvlášť rozlišujte přístup agenta a přístup stránky. MCP může připojit nástroj k Claude Code, ale publikovaná aplikace potřebuje vlastní integraci. Ukončená relace agenta by neměla zastavit požadavky webu, pokud jsou implementovány v samotné aplikaci.