Slovník pojmů

API: co to je a jak funguje

API není jen HTTP endpoint. Je to dohoda mezi programy o dostupných operacích, datech, zabezpečení i chybových stavech.

Stručná definice

API je smlouva mezi dvěma částmi softwaru.

API znamená Application Programming Interface. Může jít o rozhraní knihovny, operačního systému, hardwarové služby nebo aplikace dostupné po síti. Webové API je jen jeden z těchto případů; endpoint je pak konkrétní vstupní adresa webového API, nikoli celé API.

U webového API klient — například e-shop, mobilní aplikace nebo integrační služba — odešle požadavek a poskytovatel vrátí odpověď. Aby spolu mohli dlouhodobě spolupracovat, musí se shodnout na kontraktu: parametrech, datovém formátu, oprávněních, významu chyb i pravidlech změn.

Použití

K čemu API slouží

API odděluje interní fungování systému od způsobu, jakým jeho data nebo funkce používají jiné programy.

napojení e-shopu na dopravce, platební bránu, účetnictví nebo marketplace
backend pro webovou či mobilní aplikaci
propojení skladu, ERP, zákaznického portálu a dalších interních systémů
opakovatelné importy, exporty a automatizované datové toky
volání funkcí knihoven nebo služeb operačního systému v rámci programu

Praktický příklad

E-shop a dopravce

Po zaplacení objednávky odešle e-shop dopravci údaje pro zásilku: interní číslo objednávky, adresu příjemce, službu dopravy a případně výdejní místo. Dopravce vrátí identifikátor zásilky a odkaz na štítek, které e-shop uloží k objednávce.

Když po odeslání nastane timeout, e-shop neví, zda dopravce zásilku vytvořil. Bezpečný kontrakt proto používá jednoznačný identifikátor odesílatele nebo idempotency key. Chybu adresy zobrazí obsluze, dočasnou chybu monitoruje a limitovaný požadavek opakuje až podle pokynu služby.

Jak funguje

Od požadavku k odpovědi

Jednoduchá výměna dat přes webové API obvykle probíhá v těchto krocích:

Kontrakt Klient zná operaci, adresu, parametry, bezpečnostní pravidla a očekávané odpovědi.
Požadavek Odešle HTTP metodu, URL, hlavičky, přihlašovací údaj a podle potřeby tělo.
Zpracování Služba ověří identitu, oprávnění a vstupy, potom provede vlastní logiku.
Odpověď Vrátí status, hlavičky a data nebo strojově čitelný popis chyby.
Provozní reakce Klient uloží výsledek, případně bezpečně řeší dočasnou chybu nebo limit.

Důležité vlastnosti

Co musí být v API jasné

Samotný JSON nestačí. Bez významu polí a pravidel chování není rozhraní spolehlivým kontraktem.

Data a dokumentace

JSON je běžný datový formát, XML přetrvává hlavně ve starších B2B, ERP a logistických integracích. OpenAPI může přesně popsat HTTP operace, vstupy, odpovědi i zabezpečení.

Autentizace a autorizace

Autentizace říká, kdo volá; autorizace, co smí udělat. API klíč, podpis nebo access token musí mít omezený rozsah, životnost, bezpečné uložení a možnost rotace.

Chyby a limity

HTTP status má odpovídat výsledku. Stabilní typ chyby a korelační ID jsou pro klienta užitečnější než obecný text. Rate limiting musí říkat, co se počítá a kdy lze požadavek opakovat.

Změny a verzování

Přidání nepovinného pole bývá kompatibilnější než jeho odstranění nebo změna významu. Důležitější než místo verze je přechodné období a předvídatelný konec podpory.

Rozhraní v praxi

Kdo v API hraje jakou roli

Pojmy se často zaměňují, přitom každý řeší jinou část komunikace.

Klient: Program, který API volá: e-shop, mobilní aplikace, worker nebo jiný systém.
Poskytovatel: Služba, která kontrakt implementuje a rozhoduje o přijetí požadavku.
Endpoint: Konkrétní vstupní URL či adresa jedné operace webového API.
Uživatelské rozhraní: Rozhraní pro člověka; API naopak potřebuje programově přesný a stabilní kontrakt.

Výhody a omezení

Co dobře navržené API přináší — a co nevyřeší

Přínosy

odděluje interní implementaci od smlouvy, na které závisejí jiné systémy
umožňuje automatizovat datové toky bez ručních exportů
dává různým klientům jeden definovaný vstup do služby
usnadňuje logování, měření a dohledání konkrétního požadavku

Časté chyby

nezdokumentované změny polí nebo významu hodnot
vracení HTTP 200 i při chybě a rozhodování podle volného textu
klíče v URL či repozitáři, záměna autentizace za autorizaci
opakování mutace po timeoutu bez ochrany proti duplicitě

Hranice použití

API samo o sobě neznamená hotovou integraci.

Síť může selhat i ve chvíli, kdy vzdálená strana požadavek úspěšně dokončila. U vytvoření objednávky nebo zásilky proto nestačí bezmyšlenkovitý retry: je nutný jednoznačný business identifikátor, idempotency key nebo dohledání aktuálního stavu.

Rozhraní také není automaticky bezpečnou hranicí systému. Validace, oprávnění, audit, stránkování velkých seznamů a reakce na výpadek externí služby jsou samostatná návrhová rozhodnutí.

Na co myslet

Pravidla pro provozně použitelné API

Kontrakt má pokrýt i situace, které nenastanou při prvním úspěšném volání.

konzistentní formát dat, časů, měn a chybových odpovědí
HTTPS, omezená oprávnění, rotace a bezpečné ukládání přístupů
stránkování, filtry a maximální limit pro velké seznamy
měřitelné limity, korelační ID, logování a monitoring
bezpečné opakování mutací podle jasně popsaných pravidel

Časté otázky

Co se o API často plete

Je API totéž co endpoint?

Ne. Endpoint je konkrétní vstupní adresa webového API. API zahrnuje i kontrakt, datové modely, zabezpečení, chyby a pravidla kompatibility.

Je API vždy přes HTTP a JSON?

Ne. API může být rozhraní knihovny, operačního systému i síťová služba. Webová API často používají HTTP a JSON, ale také XML, jiné protokoly nebo asynchronní zprávy.

Jaký je rozdíl mezi API a uživatelským rozhraním?

Uživatelské rozhraní je určené člověku. API je určené jinému programu, proto potřebuje přesnou smlouvu místo ovládacích prvků.

Musí být každé webové API REST?

Nemusí. REST je konkrétní architektonický styl. Pro některé případy je vhodnější jiné HTTP API, RPC nebo asynchronní zpracování.

Jak API používám v praxi

Integrace nejsou jen několik endpointů.

V praxi řeším napojení e-shopů a interních systémů na externí služby, importy, synchronizace i chybové stavy provozu.

Jak pracuji s API a integracemi Nezávazně probrat projekt