Práce s API třetích stran: jak číst dokumentaci a nezbláznit se.

Dřív nebo později budeš chtít, aby tvoje aplikace mluvila s cizí službou. Posílala e-maily, brala platby, tahala počasí, napojila se na AI. K tomu slouží API třetích stran a jejich dokumentace umí na první pohled pořádně vyděsit. Ukážu ti, jak v té záplavě najít to podstatné a napojení zvládnout bez nervů, klidně i s pomocí AI.

Co je API a proč ho potřebuješ

API je domluvený způsob, jak si dvě aplikace povídají. Představ si ho jako číšníka v restauraci. Ty (tvoje aplikace) si objednáš podle jídelního lístku (dokumentace), číšník (API) odnese objednávku do kuchyně (cizí služba) a přinese ti, co jsi chtěl. Nemusíš vědět, jak kuchyně funguje uvnitř, stačí umět objednat.

Díky API nemusíš všechno stavět sám. Nechceš programovat vlastní platební bránu nebo vlastní jazykový model, jen je zavoláš přes jejich API. K obecnému principu napojení mrkni na napojení aplikace na databázi a API.

Skoro každá moderní aplikace je dnes slepenec z cizích služeb. Přihlášení přes Google, platby přes platební bránu, e-maily přes specializovanou službu, mapy z jiného poskytovatele. To všechno jsou API třetích stran. Naučit se s nimi pracovat je proto jedna z nejcennějších dovedností, kterou jako tvůrce aplikací můžeš mít, a vyplatí se ti na každém dalším projektu.

Čtyři věci, které v dokumentaci hledej jako první

Dokumentace bývá obrovská, ale ty z ní pro start potřebuješ jen čtyři věci. Najdi je a zbytek zatím ignoruj:

1. Jak se přihlásit (autentizace): skoro vždy potřebuješ API klíč, takové heslo pro tvoji aplikaci.
2. Adresa (endpoint): URL, na kterou se posílá požadavek pro konkrétní věc.
3. Co poslat: jaká data a v jaké podobě služba čeká na vstupu.
4. Co dostaneš zpátky: jak vypadá odpověď, ať víš, kde si vzít výsledek.

Když si tyhle čtyři věci vypíšeš, máš v ruce všechno potřebné. Zbytek dokumentace jsou většinou pokročilé možnosti, které zatím nepotřebuješ.

Hledej sekci pro rychlý start

Skoro každá slušná dokumentace má sekci jako quickstart, getting started nebo prvních pět minut. Tam ti ukážou nejjednodušší možný příklad, jak službu zavolat. Vždycky začni tady, ne u kompletního výpisu všech funkcí.

Tenhle příklad si zkopíruj, dosaď svůj API klíč a zkus ho spustit. Když ti vrátí odpověď, máš vyhráno, spojení funguje a zbytek je už jen stavění na tomhle základě.

Postupuj po malých krocích, ne všechno naráz

Velká chyba je chtít hned napsat celou složitou integraci a doufat, že to vyjde. Místo toho postupuj po krůčcích a každý si ověř, než jdeš dál. Tady je pořadí, které mi vždy zafunguje:

1. Nejdřív si ověř přihlášení: pošli ten nejjednodušší možný požadavek a koukni, jestli tě služba pustí dál.
2. Pak si vyzkoušej čtení dat: vytáhni něco jednoduchého a podívej se, jak odpověď vypadá.
3. Teprve potom zkus zápis: odešli reálnou věc, třeba testovací e-mail nebo testovací platbu.
4. Nakonec napoj API na svoji aplikaci a ošetři, co se stane, když volání selže.

Když narazíš na problém, hned víš, ve kterém kroku to bylo. Kdybys napsal všechno naráz, hledal bys chybu ve velké hromadě kódu a nevěděl, kde začít.

Jak vypadá volání API v praxi

Tady je zjednodušený příklad, jak voláš API e-mailové služby, abys odeslal zprávu. Všimni si těch čtyř věcí z předchozí sekce: adresa, klíč, co posílám, co čekám zpátky.

const odpoved = await fetch("https://api.sluzba.cz/v1/email", {
  method: "POST",
  headers: {
    "Authorization": "Bearer TVUJ_API_KLIC",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    komu: "zakaznik@example.com",
    predmet: "Dekujeme za objednavku",
    text: "Vase objednavka byla prijata."
  })
});

const vysledek = await odpoved.json();
console.log(vysledek);

I když každé API vypadá trochu jinak, princip je pořád stejný. Jakmile pochopíš tenhle vzor, čtení jakékoli další dokumentace je hned snazší.

Jak ti AI pomůže s dokumentací

Tady je AI obrovský pomocník. Když narazíš na kus dokumentace, kterému nerozumíš, prostě jí ho vlož a popiš, co chceš udělat. AI ti často rovnou napíše funkční kód na míru tvému jazyku a frameworku.

Dobrý prompt zní třeba takhle:

Tady je část dokumentace platební služby. Chci v aplikaci v JavaScriptu vytvořit platbu na 500 Kč. Napiš mi funkci, která to udělá, a vysvětli, kam mám dát svůj API klíč.

Pozor ale na jednu věc: API klíče jsou jako hesla. Nikdy je nedávej do kódu, který se dostane na veřejnost, a nevkládej je do promptu zbytečně. Víc o tomhle riziku v bezpečnost aplikace pro neprogramátory.

Časté chyby a jak je poznat podle odpovědi

API ti při chybě obvykle vrátí číselný kód, který ti přesně řekne, co je špatně:

• 401 nebo 403: problém s přihlášením, špatný nebo chybějící API klíč.
• 400: poslal jsi špatná data, třeba ti chybí povinné pole nebo máš překlep.
• 404: špatná adresa, voláš endpoint, který neexistuje.
• 429: posíláš moc požadavků moc rychle, musíš zpomalit.
• 500: chyba na straně služby, tady už nic nezmůžeš, jen to zkus později.

Časté dotazy

Kde vezmu API klíč?

Skoro vždy se nejdřív zaregistruješ na webu té služby a v nastavení účtu si klíč vygeneruješ. Často je v sekci jako Developers, API nebo Nastavení. Klíč si dobře ulož a nikomu ho neukazuj.

Musím platit za používání cizích API?

Záleží na službě. Mnoho jich má štědrou zkušební nebo zdarma úroveň, která ti na začátek bohatě stačí. Platit začneš až při větším objemu. Vždy si dopředu zkontroluj ceník, ať tě nepřekvapí účet.

Co když dokumentace nemá příklad v mém jazyce?

To nevadí. Princip volání je všude stejný, jen syntaxe se liší. Vlož příklad v jiném jazyce do AI a požádej ji o převod do toho tvého. Většinou to zvládne na první pokus.

Pokud potřebuješ napojit aplikaci na platby, e-maily, AI nebo jinou službu a nechceš se topit v dokumentaci, napiš mi přes kontakt. Integrace cizích API dělám běžně a rád to vyřeším za tebe nebo tě tím provedu.