API a FastAPI jednoducho

API je spôsob, akým sa programy obracajú jeden na druhý. Jeden žiada, druhý odpovedá. Na príklade online trhoviska si rozoberieme, z čoho sa skladá požiadavka, ako čítať JSON odpoveď a čo overiť, keď Claude Code pripája externý zdroj údajov. Na konci stručne upresníme, kde sa tu môže objaviť FastAPI.

Čo je API jednoducho

API (Application Programming Interface) je programové rozhranie. Určuje dostupné operácie a pravidlá, ako ich používať. API majú nielen jednotlivé aplikácie, ale aj knižnice, operačný systém, prehliadač. Cez neho môže program požiadať iný program alebo jeho časť, aby niečo urobil, a dostať výsledok. Tu budeme hovoriť hlavne o sieťových API, na ktoré sa obraciame cez adresu.

Predstavte si reštauráciu. Ako zákazník nechodíte do kuchyne a nevysvetľujete kuchárovi, ako má variť. Čašníkovi poviete, čo si z jedálneho lístka želáte, on odnesie objednávku do kuchyne a prinesie vám hotové jedlo. API je čašník. Klientsky program cez neho zadáva objednávku a kuchyňa (iný program) ju vybaví. Nemusíte vedieť, ako je všetko vnútri zariadené. Stačí poznať menu a rozumieť, o čo môžete požiadať a čo príde v odpovedi.

V podstate je API zmluva: "obracajte sa na mňa takto a v odpovedi vrátim takýto výsledok".

Existuje aj krátke vtipné video v angličtine - "How API work". Je to obrázok k tej istej myšlienke, nie vysvetlenie témy. Všetko potrebné je v texte nižšie.

Požiadavka a odpoveď na príklade trhoviska

Predstavte si online trhovisko, na ktoré dodávateľ posiela tovar zo svojho programu. Prenášať tisíce položiek cez tlačidlá webu je nepohodlné, preto trhovisko poskytuje programové operácie API. Napríklad POST /products pridá tovar a GET /reports vráti prehľad.

Adresa dostupnej operácie sa nazýva endpoint. Aby sme požiadavke porozumeli, pozeráme sa na adresu aj na HTTP metódu. GET /products a POST /products môžu vykonávať rôzne akcie. GET sa zvyčajne používa na čítanie, POST na odovzdanie údajov na spracovanie.

Údaje sa často prenášajú vo formáte JSON. Zložené zátvorky spájajú polia objektu, reťazce sa píšu v úvodzovkách a zoznam objektov v hranatých zátvorkách:

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

Klient odošle požiadavku, server ju spracuje a vráti odpoveď. Nižšie je zjednodušená schéma výmeny, nie úplný HTTP paket:

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

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

201 Created je stav odpovede a JSON pod ním je telo s výsledkom. V skutočnom API dokumentácia uvádza endpoint, metódu, povinné parametre, hlavičky, tvar odpovede a možné chyby. Bezpečnejšie je začať jedným testovacím objektom, nie celou sadou údajov.

Frontend, backend a API medzi nimi

API netreba len na prepojenie rôznych aplikácií. Jedna aplikácia sa často sama vnútri skladá z dvoch programov a aj tie sa medzi sebou dorozumievajú cez API.

Frontend je časť aplikácie, s ktorou pracujete v prehliadači. Patria k nemu tlačidlá, obrázky, menu, formuláre a správanie stránky. Jeho programovú logiku zvyčajne píšu v JavaScripte. Dokáže sám vykonávať zložité výpočty aj sa obracať na server, keď potrebuje údaje alebo akcie na strane služby.

Backend je serverová časť aplikácie. Spracúva platby, ukladá objednávky, kontroluje prístup, vyhľadáva tovar. Počas vývoja môže server bežať na vašom počítači, po publikovaní na hostingu. Používateľ jeho zdrojový kód spolu so stránkou nedostane. Do prehliadača prichádzajú odpovede na požiadavky.

Ako sa spolu dorozumievajú? Cez to isté API. Backend poskytuje endpointy nielen externým dodávateľom, ale aj vlastnému frontendu:

• otvorili ste stránku - frontend zavolá endpoint /products/list, backend vráti zoznam tovaru, frontend ho pekne vykreslí;
• klikli ste na "kúpiť" - frontend pošle údaje na endpoint /orders, backend vybaví objednávku.

Takže cez API sa môžu dorozumievať rôzne aplikácie aj časti jednej aplikácie. V tejto schéme prehliadač pošle požiadavku, backend pracuje s údajmi a vráti výsledok. Databáza nemusí byť prehliadaču dostupná priamo.

Požiadavka z prehliadača

Vyššie sme povedali, že frontend "volá endpoint" backendu. Pozrime sa, ako to vyzerá v kóde. Prehliadač má na to vstavanú funkciu fetch. Odošle HTTP požiadavku na potrebnú adresu a vráti odpoveď. Telo odpovede zvyčajne prichádza v JSON a na objekt ho rozparsuje metóda .json().

Zoberme si číselník lokalít - kombinácií jazyka a regionálnych nastavení. Predpokladajme, že backend už vie vrátiť zoznam na adrese /locales a frontend ho má zobraziť. Server vracia napríklad:

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

Ako prichádza odpoveď

Fragment nižšie sa vykonáva vo vnútri asynchrónnej funkcie obsluhy stránky. Získa údaje; vykreslenie tabuľky tu nie je ukázané.

const res = await fetch("/locales");
if (!res.ok) {
  throw new Error(`HTTP ${res.status}`);
}
const locales = await res.json();
// Teraz locales obsahuje údaje pre tabuľku

res.ok kontrolujeme ešte pred čítaním údajov. HTTP chyba ako 404 alebo 500 sama osebe nespôsobí, že by fetch skončil výnimkou. Samostatne sa môže stať, že sieťová požiadavka neprebehne alebo sa JSON nepodarí rozparsovať. Chybu z takéhoto fragmentu má zachytiť kód stránky a zobraziť zrozumiteľnú správu. Sú to rôzne príčiny, hoci používateľ vo všetkých prípadoch údaje nedostal. Podrobnosti sú v príručke MDN na fetch.

Je tu pár drobností, ktoré sa ľahko prehliadnu:

• predvolene fetch robí GET - požiadavku na získanie údajov. Iné operácie sa zadávajú metódou; napríklad naše trhovisko prijíma nový tovar cez POST;
• adresa /locales je relatívna. V bežnej HTTP stránke sa obracia na koreň toho istého origin. Origin určuje schéma, host a port; server musí mať takú cestu;
• fetch a .json() nevracajú výsledok hneď, preto sa pred ne píše await - "počkaj na odpoveď".

Ak otvoríte HTML ako súbor cez file://, zápis /locales sa nestane adresou vášho HTTP servera. Pre tento príklad sa stránka otvára cez server, na ktorom je táto cesta implementovaná. Samotný súbor HTML takú cestu nevytvorí.

Frontend a API môžu byť na rôznych origin. Aby potom prehliadač mohol odpoveď prečítať, server API musí povoliť potrebný prístup cez CORS. Je to mechanizmus prístupu medzi rôznymi origin, nie názov akejkoľvek sieťovej chyby. Umiestnenie stránky a API na jeden origin príklad zjednodušuje, ale nie je povinné pre všetky aplikácie. Podrobnosti sú v popise CORS na MDN.

Kto odpovedá prehliadaču

Kto odpovedá na fetch("/locales")? Backend, a ten nemusí byť v Pythone s FastAPI. API je dohoda medzi programami, nie konkrétny jazyk. Ten istý endpoint sa dá napísať v Node.js, Go alebo Jave. Napríklad v obsluhe servera Node.js môžete vrátiť pripravené pole locales. Nižšie je len fragment obsluhy, nie hotový server:

// req a res dostala obsluha, locales je pripravené vopred
if (req.method === "GET" && req.url === "/locales") {
  res.statusCode = 200;
  res.setHeader("Content-Type", "application/json; charset=utf-8");
  res.end(JSON.stringify(locales));
}

Zvonka je to stále tá istá HTTP požiadavka GET /locales a v odpovedi je stav 200 a JSON. Frontend nemusí vedieť, v čom je backend napísaný. Potrebuje adresu, pravidlá požiadavky a formát odpovede.

Aké API existujú

API sa dajú pohodlne rozdeliť podľa dvoch znakov:

• lokálne a sieťové - napríklad API knižnice sa volá z kódu programu, kým na sieťové API sa obraciame cez sieť. Sieť môže byť aj interná, bez otvoreného internetu;
• verejné a interné - verejné sú určené pre externých vývojárov, interné spájajú časti systému. Verejné API môže tiež vyžadovať registráciu, platbu a povolenia.

Webové API často používajú HTTP - protokol požiadaviek a odpovedí. REST, s ktorého názvom sa stretnete v dokumentácii, opisuje prístup k návrhu API; nie každé HTTP API automaticky zodpovedá REST. Zatiaľ je užitočnejšie naučiť sa čítať stavový kód v odpovedi:

• 200 - všetko je v poriadku;
• 201 - vytvorené (napríklad nový objekt po POST);
• 404 - nenájdené;
• 401 - požiadavka neobsahuje vhodné autentifikačné údaje;
• 429 - príliš veľa požiadaviek;
• 500 - interná chyba servera.

Hlboko sa do toho teraz ponárať nemusíte. Dôležité je zachytiť samotnú myšlienku výmeny požiadaviek a odpovedí. Zatiaľ to stačí.

Prečo služba potrebuje prístupový kľúč

Mnohé služby najprv žiadajú získať API kľúč - reťazec spojený s vaším účtom alebo projektom. Odovzdáva sa spôsobom uvedeným v dokumentácii, často v hlavičke požiadavky. Služba overí prístup a môže evidovať, koľko požiadaviek ste urobili. V iných integráciách narazíte na slovo token. Má podobný účel, ale spôsob získania, platnosť a práva sa môžu líšiť.

Bez vhodného prístupu sa požiadavka nevykoná; server napríklad môže odpovedať 401. Prekročenie frekvencie požiadaviek sa často označuje kódom 429. Presný význam odpovede a povolené objemy hľadajte v dokumentácii konkrétnej služby. Existujú aj otvorené zdroje, ktoré kľúč vôbec nepotrebujú.

Kde hľadať hotové API

Cez API sa do aplikácií vkladajú mapy, počasie, platby a doručovanie. Otvorená dokumentácia pomáha pochopiť možnosti služby ešte pred pripojením. Lepšie je začať samotnou úlohou. Ujasnite si, aké údaje potrebujete, ako často sa majú aktualizovať a čo s nimi chcete robiť.

Na hľadanie sa hodí pozrieť Postman Public API Network, katalóg API a príkladov požiadaviek. Nájdený príklad je len východiskový bod. Adresu, formát, prístup a obmedzenia aj tak overte v oficiálnej dokumentácii vlastníka služby.

Kde je tu FastAPI

FastAPI je jeden z frameworkov na tvorbu API a webových serverov v Pythone. Dokáže prepojiť endpoint s vaším serverovým kódom, prijať požiadavku a vrátiť JSON odpoveď. FastAPI potrebujete, keď vytvárate vlastný backend v Pythone; na používanie hotového API ho študovať netreba. Na úrovni 7 stačí názov spoznať a rozumieť tejto hranici.

Ako to funguje v spojení s Claude Code

S týmito pojmami sa prácu agenta hodnotí ľahšie. Agent môže prečítať dokumentáciu cudzieho API, napísať klientsku požiadavku alebo vytvoriť vaše vlastné API vo FastAPI. Pre vás je dôležité vidieť konkrétnu cestu od požiadavky až k údajom na stránke. Kto posiela požiadavku, kto odpovedá a ako sa odpoveď spracuje?

Napríklad pre radar zemetrasení existuje verejný GeoJSON feed USGS. Adresa zoznamu za poslednú hodinu:

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

Nižšie je malý výučbový príklad štruktúry odpovede s vymyslenou udalosťou a skrátenou sadou polí. Nie sú to aktuálne údaje USGS:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "mag": 4.2, "place": "Výučbový bod" },
      "geometry": { "type": "Point", "coordinates": [-122.5, 38.0, 8.0] }
    }
  ]
}

V features je pole udalostí. Cesta features[0].properties.mag vedie k magnitúde prvej z nich. Index 0 znamená prvý prvok poľa. Súradnice idú v poradí "zemepisná dĺžka, zemepisná šírka, hĺbka v kilometroch". Agent môže použiť magnitúdu na veľkosť bodu a súradnice na jeho polohu. Ak je pole prázdne, prvý prvok neexistuje; ak sa magnitúda rovná null, je to neznáma hodnota, nie nulová sila udalosti.

Zostáva rozhodnúť, čo zobraziť po požiadavke:

Kým sa požiadavka vykonáva, stránka môže zobrazovať načítavanie. Na overenie rôznych výsledkov sa hodia výučbové odpovede. Nemusíte tak čakať na skutočnú poruchu služby alebo nové zemetrasenie.

Zadanie pre Claude Code teraz môže znieť takto:

Pripoj k stránke údaje z uvedeného API.
Najskôr skontroluj oficiálnu dokumentáciu: adresu, metódu,
formát odpovede a podmienky prístupu. Ukáž, ktoré polia používaš.
Počítaj s načítavaním, prázdnym zoznamom a chybou aktualizácie.
Ak po poruche používaš staré údaje, vyznač to na stránke.
Nevkladaj tajný kľúč do klientskeho kódu.
Over výsledok a napíš, ktoré stavy sa podarilo overiť.

Po skončení práce si pozrite samotnú požiadavku a výsledok overenia, nielen hotový obrázok. Zvlášť rozlišujte prístup agenta a prístup stránky. MCP môže pripojiť nástroj ku Claude Code, ale publikovaná aplikácia potrebuje vlastnú integráciu. Zatvorená relácia agenta nemá zastaviť požiadavky webu, ak sú implementované v samotnej aplikácii.