API bez magie: Co se skutečně stane mezi dvěma aplikacemi

Když vše funguje, může výměna trvat například 300 milisekund. Při chybě je důležité vědět, co přesně znamená hláška „Synchronizace se nezdařila“. Taková zpráva nepomůže uživateli ani člověku, který hledá příčinu problému.

Co se skutečně stane mezi dvěma aplikacemi

Představme si malý e-shop. Po zaplacení objednávky má účetní aplikace vystavit fakturu.

Výměna může proběhnout takto:

1. E-shop zjistí, že zákazník zaplatil.
2. Připraví požadavek pro účetní aplikaci. Uvede v něm zákazníka, položky objednávky, ceny, sazby DPH a variabilní symbol.
3. Přidá přístupový token. Účetní aplikace podle něj pozná, kdo požadavek posílá a jaké operace smí provádět.
4. Požadavek odešle přes internet na určenou adresu API, například /invoices.
5. Účetní aplikace ověří token a data. Pokud něco chybí, fakturu nevytvoří.
6. Když je vše v pořádku, založí fakturu a odpoví jejím číslem a stavem.
7. E-shop si odpověď uloží k objednávce.

Data se často posílají ve formátu JSON. Jde o sadu pojmenovaných hodnot, například číslo objednávky, e-mail, částku a měnu. Pro uživatele není podstatné umět JSON psát. Důležité je, aby obě aplikace stejným údajům rozuměly stejně.

Například částka 1500 sama o sobě nestačí. Může znamenat 1 500 Kč, 15,00 Kč vyjádřených v haléřích nebo 1 500 eur. Takové nejasnosti vedou k chybám při zpracování dat.

Součástí odpovědi bývá stavový kód. Kód 201 může znamenat, že faktura vznikla. 400 obvykle označuje chybná nebo neúplná data. 401 říká, že odesílatel nemá platné přihlášení. 429 znamená příliš mnoho požadavků. Kódy začínající pětkou většinou ukazují na problém na straně přijímající aplikace.

Tím práce nekončí. Aplikace musí vědět, co udělat při výpadku. Má požadavek zopakovat za minutu? Kolikrát? Nevytvoří opakování dvě stejné faktury? Pravidla pro opakování požadavků, ochranu proti duplicitám a evidenci chyb rozhodují o tom, zda napojení bude fungovat i při výpadcích.

Na čem se API pozná v praxi

API samo o sobě obvykle nevidíte. Vidíte jeho důsledky. Objednávka se přenese bez přepisování. Ve skladu se změní dostupné množství. Dopravce dostane údaje k zásilce. V CRM vznikne kontakt.

Z technického pohledu má API dokumentaci. Ta popisuje dostupné adresy, povolené operace, požadovaná data, způsob přihlášení a možné odpovědi. Před zahájením práce je vhodné ověřit pět věcí: zda API vůbec existuje, zda dovoluje potřebnou operaci, jak se získá přístup, jaká má omezení a zda nabízí testovací prostředí.

Nápis „máme API“ ještě neznamená, že přes něj lze udělat vše. Některé systémy dovolí fakturu načíst, ale ne vytvořit. Jiné zpřístupní objednávky, avšak bez informace o jejich úhradě. Rozhodující je vždy konkrétní rozsah dostupných operací a dat.

Důležité jsou také záznamy o komunikaci. U každého požadavku potřebuji dohledat čas, cílovou adresu, výsledek a srozumitelný popis chyby. Citlivá data a přístupové tokeny se do záznamu ukládat nemají. Když napojení selže, věta „ve 14:03 účetní systém odmítl objednávku 5821, protože chybělo DIČ“ umožní chybu dohledat. Obecná informace o selhání většinou nestačí.

Kdy firma API potřebuje a kdy je zbytečné

API dává smysl tam, kde se stejná data přenášejí opakovaně, podle stabilních pravidel a bez potřeby lidského úsudku. Typicky jde o objednávky, faktury, skladové zásoby, kontakty nebo stavy zásilek.

Vyplatí se začít jednoduchým výpočtem. Pokud člověk přepisuje 20 objednávek denně a jedna zabere tři minuty, za 20 pracovních dnů je to 20 hodin. Pak lze porovnat cenu napojení s cenou práce a chyb. Podrobněji tento způsob rozhodování popisuji v článku o tom, kdy firma API integraci opravdu potřebuje.

Naopak kvůli pěti záznamům měsíčně bych vlastní napojení většinou nestavěl. Levnější může být export do CSV, ruční import nebo hotová automatizace. Pro jednoduchý tok mezi běžnými nástroji může stačit low-code nebo no-code nástroj. Nehodí se ale tam, kde jsou složité výjimky, velké objemy nebo vysoké nároky na dohledání chyb.

API také nevyřeší nejasný proces. Když ve firmě nikdo neví, kdy je objednávka skutečně připravená k fakturaci, automatizace jen rychleji přenese nejasnosti do dalších systémů. To bývá součást digitálního dluhu, tedy stavu, kdy data a pravidla nejsou dost spolehlivá pro automatické zpracování.

S čím se API nejčastěji plete

API není totéž co integrace. API je rozhraní, které aplikace nabízí. Integrace je konkrétní propojení, které toto rozhraní používá a řeší také převod dat, chyby, opakování a dohled.

API není databáze. Přímý zápis do databáze může vypadat jako rychlé řešení, ale obchází pravidla aplikace. Po aktualizaci systému se může změnit struktura databáze nebo způsob, jakým aplikace data zpracovává.

API také není webhook. Při běžném dotazu se aplikace aktivně ptá, zda se něco změnilo. Webhook funguje opačně. Druhá aplikace sama pošle upozornění, například hned po zaplacení objednávky. V praxi se oba způsoby často kombinují.

A nakonec, API není automatické klikání v uživatelském rozhraní. Robot může napodobovat člověka, ale změna tlačítka nebo formuláře ho snadno rozhodí. API bývá stabilnější, protože je určené pro komunikaci aplikací.

API lze přirovnat k podatelně. Odesílající aplikace musí znát adresu, prokázat oprávnění, poslat správně vyplněný formulář a vyhodnotit potvrzení o přijetí. Bez této odpovědi neví, zda druhá aplikace požadavek skutečně zpracovala.