API, webhook, nebo ruční export pro propojení firemních systémů

Když mají 2 systémy sdílet data, existují 3 běžné cesty. Člověk může stáhnout soubor z jednoho systému a nahrát ho do druhého. Webhook, tedy automaticky odeslané hlášení, může druhý systém upozornit na změnu. API, tedy programové rozhraní, umožní druhému programu aktivně číst nebo zapisovat data.

Dřív jsem začínal otázkou, zda se systémy propojit dají. Samotná technická možnost ale nestačí k rozhodnutí, zda propojení dává smysl. Při dostatku času lze propojit mnoho systémů, ale výsledné řešení může být náročné na správu. Dnes nejdřív zjišťuji, jak rychle se mají data přenést a co se má stát při chybě.

Podle čeho cesty řadím

Pořadí určuji podle toho, jak velkou část procesu cesta zvládne bez člověka. API je na 1. místě, protože propojení přes něj může číst a zapisovat data, dohledávat stav a opravovat rozdíly. Webhook je na 2. místě, protože rychle spouští reakci, ale obvykle nezajišťuje celý přenos. Ruční export je na 3. místě, protože člověk zůstává součástí každého běhu. Nejde však o známky kvality. Při přenosu 1× měsíčně může ruční export překonat API cenou i jednoduchostí.

Při rozhodování sleduji frekvenci přenosu, přijatelné zpoždění, směr dat, následky chyby a nároky na údržbu. Směr dat určuje, zda stačí údaje pouze převzít, nebo se mají změny vracet. Jiný následek má chyba v pomocném reportu, jiný dvojí založení objednávky. Údržba zahrnuje změny polí, přístupů a verzí rozhraní. Bez těchto údajů nelze pořadí jednotlivých cest spolehlivě určit.

1. API pokryje největší část procesu

API volím, když má propojení podle zadaných pravidel určit, která data načíst, co zapsat a jak ověřit výsledek. Hodí se pro pravidelný přenos objednávek, stavů faktur, skladových údajů nebo kontaktů. Pokud rozhraní zpřístupňuje potřebná data, lze přes něj načíst historii při úvodním spuštění a později přenášet jen změny. Jak vypadá samotná výměna požadavků a odpovědí, popisuji v článku API bez magie.

To, že se lze k API připojit, ještě neznamená, že rozhraní poskytuje potřebná data a operace. Před návrhem si nechám ukázat dokumentaci, testovací prostředí a příklady odpovědí. Ověřím také limity počtu požadavků, způsob přihlášení, dostupná pole a pravidla pro změny rozhraní. Pak určím, který systém je zdrojem pravdy, tedy čí hodnota platí při konfliktu. Jinak může integrace automaticky přepsat správný údaj nesprávným.

API se nehodí pro vzácný a snadno kontrolovatelný přenos. Nevolím ho ani tehdy, když dodavatel nabízí jen část potřebných funkcí a zbytek by dál vyžadoval ruční zásah. Před psaním kódu používám 5 otázek k API mezi 2 systémy. Odpovědi zapíšu přímo do zadání včetně toho, kdo řeší chybu a podle čeho pozná, že je přenos hotový.

2. Webhook je nejrychlejší spouštěč

Webhook se hodí, když má druhý systém reagovat hned po konkrétní události. Zdroj může oznámit založení požadavku, zaplacení faktury nebo změnu stavu objednávky. Druhý systém se pak nemusí každých 5 minut ptát, zda se něco změnilo. Zpráva někdy obsahuje všechna data, jindy jen identifikátor, tedy jedinečné označení záznamu. Příjemce si pak podrobnosti stáhne přes API.

Webhook sám nezaručuje bezchybné doručení ani správné pořadí zpráv. Stejná událost může přijít opakovaně a některá zpráva při výpadku nemusí dorazit. Každou událost proto ukládám s jejím jedinečným identifikátorem. Událost s již uloženým identifikátorem nezpracovávám znovu. Příjem zpráv také odděluji od další práce pomocí fronty, tedy seznamu úloh čekajících na zpracování. Systém zprávu rychle převezme a vlastní zápis dokončí až potom.

Při testu záměrně na 10 minut vypnu příjem, pošlu stejnou událost 2krát a obrátím pořadí 2 změn. Ověřím také podpis zprávy, který slouží ke kontrole jejího původu. Když tyto scénáře nemají jasný výsledek, řešení založené na webhooku není připravené na provoz. Webhook se nehodí ani pro úvodní import historie nebo pravidelné porovnání všech záznamů. Tam potřebuje pomoc API nebo exportu.

3. Ruční export je někdy správně

Ruční export volím pro občasný přenos, u kterého nevadí čekání a člověk data stejně kontroluje. Typickým formátem je CSV, jednoduchá textová tabulka se sloupci a řádky. Technická investice je malá a postup lze změnit bez zásahu vývojáře. Je to rozumná volba také tehdy, když některý systém nemá použitelné API.

Jednoduchost souboru ale může být klamná. Stačí přejmenovaný sloupec, jiný oddělovač hodnot nebo tabulka otevřená v programu, který změní zápis data. Proto připravím pevnou šablonu, určím povinné sloupce a pro každý záznam zachovám jedinečný identifikátor. Nejdřív zkouším import na kopii dat. Po skutečném přenosu ukládám původní soubor, čas provedení a výsledek importu. Při chybě pak lze dohledat, s jakým souborem import pracoval a jak skončil.

Export se nehodí tam, kde starý údaj okamžitě ovlivní další krok, například rezervaci zásoby nebo opakované odeslání dokladu. S rostoucí frekvencí a počtem výjimek přibývá ruční práce. Než export nahradím, nechám 2 týdny zapisovat čas práce, počet oprav a důvod každé chyby. Teprve změřený provoz ukáže, zda dává smysl API, webhook, nebo nástroj bez klasického programování. U takového nástroje hlídám licence a správu stejně jako u vývoje, protože No Code a Low Code nešetří automaticky.

Když se 3 cesty doplňují

V praxi se tyto cesty často kombinují. Webhook oznámí změnu a předá identifikátor. API podle něj načte aktuální data, provede zápis a uloží výsledek. 1× za noc může API porovnat záznamy a zachytit událost, která nedorazila. Ruční export zůstane jako schválená náhradní cesta pro delší výpadek. Každá část tak plní úlohu, pro kterou se hodí.

Potvrzení o přijetí jsem dříve považoval za důkaz, že je záznam skutečně zpracovaný. Potvrzení ale dokládalo jen jeho převzetí. Od té doby rozlišuji stav převzato, zpracováno a zamítnuto a ke každému ukládám čas i důvod. Bez této evidence nelze při chybě spolehlivě určit, kde se zpracování zastavilo.