Jak navrhnout spolehlivé zpracování chyb API

Objednávka z e-shopu dorazí, ale systém správy zásob právě neodpovídá. Zákazník obdrží potvrzení, ale objednávka se neobjeví na seznamu úkolů ve skladu. O dvě hodiny později se kolega snaží tuto situaci rozluštit z tabulky a ručně zaznamenává data. Toto není jednoduchá technická chyba: může vést k rozdílům v zásobách, zpožděním v dodávkách, chybnému fakturování a ztrátě důvěry. Proto otázka není jen, jak navrhnout zpracování chyb API, ale také jak udržet obchodní proces pod kontrolou v případě systémové chyby.

API obvykle znamenají propojení mezi systémy. Spojují e-shop s ERP, přepravní službou, fakturačním systémem, systémem pro řízení vztahů se zákazníky nebo výrobní aplikací. Dokud jsou všechny odpovědi rychlé a úspěšné, toto propojení je neviditelné. V případě chyby se však ukáže, zda informace skutečně prošly, kdo je zodpovědný za další krok a zda existuje způsob, jak bezpečně pokračovat v práci.

Zpracování chyb začíná u obchodních důsledků

První chybou v mnoha organizacích je, že všechny neúspěšné API volání jsou považovány za stejnou kategorii. Přitom je podstatný rozdíl mezi tím, zda je přepravní služba nedostupná po dobu pěti sekund, zda se připojujeme k partnerskému systému s chybným identifikátorem, nebo zda v objednávce chybí poštovní směrovací číslo.

Technická zpráva sama o sobě zřídka pomáhá operačnímu týmu. „400 Bad Request“ neříká, zda lze objednávku opravit, znovu odeslat, nebo zda je třeba se dohodnout se zákazníkem. „500 Internal Server Error“ neodpovídá na to, zda se objednávka ztratila, čeká na zpracování, nebo zda již byla vytvořena v cílovém systému a pouze odpověď se ztratila.

Před psaním vývojových pravidel je vhodné projít si proces pro každou důležitou integraci. Co spouští přenos dat? Který systém je vlastníkem dat? Co se stane, pokud přenos selže? Kdo to vidí, v jaké lhůtě a jak lze opravu zkontrolovat? Objednávka, faktura nebo výrobní instrukce se nesmí stát „nejistým stavem“ dat jen proto, že mezi dvěma systémy došlo k dočasné komunikační poruše.

Jak navrhnout zpracování chyb API pro jednotlivé procesy?

Dobrý návrh nezačíná jedním obecným seznamem chyb, ale identifikací kritických obchodních událostí. Přenos objednávky z e-shopu vyžaduje jinou ochranu než synchronizace obrázku produktu. Vytvoření faktury nebo rezervace výrobních zásob může způsobit finanční nebo provozní problémy i při jediném duplicitním požadavku. Aktualizace denního reportu obvykle snese několikaminutové zpoždění, pokud zůstane přesnost dat zachována.

U každého procesu je užitečné položit si tři otázky:

1. Jaký je obchodní dopad chyby, pokud data neprojdou včas?
2. Lze operaci opakovat bez škodlivých vedlejších účinků?
3. Kdy je nutné lidské rozhodnutí a kdy lze situaci automaticky napravit?

Na základě odpovědí na tyto otázky lze vytvořit přiměřené zpracování chyb. Ne každá chyba vyžaduje okamžité upozornění. Pokud ne kritická aktualizace dat dorazí se zpožděním tří minut, neustálé telefonické upozorňování spíše vytváří hluk. Pokud však kvůli neúspěšné rezervaci zásob e-shop prodává produkt, který již není na skladě, je nutné okamžité a jasné řešení.

Mějte jasné typy chyb

Chyby je vhodné seskupovat nejen podle HTTP kódů, ale také podle způsobu zpracování. Mezi dočasné chyby patří například přerušení sítě, přetížený partnerský systém nebo vypršelý časový limit. U těchto chyb je opakování obvykle oprávněné. Trvalé chyby, jako je chybná autorizace nebo změněné API připojení, se opakováním nevyřeší. Zde je nutný technický zásah.

Třetí skupinou jsou chyby obchodních dat nebo pravidel. Může to být chybějící daňové číslo, neexistující číslo položky, uzavřený stav objednávky nebo nepovolená sleva. Systémy by měly tyto chyby srozumitelně sdělit odpovědnému pracovníkovi: co je třeba opravit, kde a co se stane po opravě.

Toto rozlišení chrání tým před tím, aby stejnou chybnou objednávku odesílal stokrát znovu, zatímco jiný, dočasně neúspěšný přenos dat se ztratí mezi každodenními úkoly.

Opakování by mělo mít hranici a pravidlo

Opakování API požadavku se může zdát jako zřejmé řešení, ale není vždy bezpečné. Pokud systém úspěšně vytvořil fakturu a pak došlo k přerušení spojení před odpovědí, opakovaný požadavek může vytvořit druhou fakturu. Totéž se může stát při zaznamenávání objednávky, žádosti o platbu nebo generování přepravního štítku.

Proto je u kritických operací nutný jedinečný identifikátor. Přijímající systém musí rozpoznat, že se jedná o opakovaný požadavek na stejnou obchodní událost, a nesmí ji provést znovu. To se nazývá idempotentní chování. Z pohledu vedení je to jednoduché: dočasná chyba by neměla vést k dvojím finančním, skladovým nebo zákaznickým komunikačním operacím.

Časování opakování by mělo být také regulováno. Několikasekundové, postupně prodlužující se čekání je v mnoha případech vhodné. Neustálé, okamžité opakování však může dále zatěžovat chybný systém a zakrývat skutečný problém. Po určeném počtu pokusů by měl být případ zařazen na kontrolovatelný seznam čekajících, aby se neztratil v logovacích souborech.

Nenechte kolegu být řešitelem chyb mezi systémy

V mnoha firmách je zpracování chyb integrace ve skutečnosti v hlavě zkušeného pracovníka. Ví, který e-mail hledat, ve kterém systému znovu spustit operaci a která data ručně upravit. To se může zdát jako rychlé řešení, ale vytváří proces závislý na osobě. V případě dovolené, nemoci nebo růstu se to okamžitě stává rizikem.

Spravovatelný systém nenechá uživatele samotného s technickou chybovou zprávou. Odpovědná role potřebuje pracovní seznam, ve kterém je vidět dotčený obchodní objekt - například identifikátor objednávky, partner nebo faktura -, příčina chyby, dosavadní pokusy a další doporučený krok. Po opravě chyby by měl proces pokračovat řádně, pokud možno bez ručního kopírování dat.

To neznamená, že každou výjimku je třeba automatizovat. Dodací podmínky objednávky významného zákazníka nebo neobvyklá výrobní položka mohou vyžadovat skutečné lidské posouzení. Cílem je, aby kolega činil rozhodnutí, nikoli lovil data mezi systémy a zadával stejnou informaci na více míst.

Protokolování a sledovatelnost: potřebujeme důkazy, ne domněnky

Když se vedoucí zeptá, „prošla tato objednávka?“, systém musí poskytnout jednoznačnou odpověď. K tomu je u každé důležité API operace potřeba sledovatelný identifikátor, časové razítko, výsledek požadavku, stav zpracování a - kde je to vhodné - podrobnou příčinu chyby. Osobní, platební nebo jiné citlivé údaje samozřejmě nelze nekontrolovaně protokolovat.

Protokol však sám o sobě není model provozu. Je třeba sledovat poměr neúspěšných volání, délku zpracovatelských front, zhoršení doby odezvy a opakující se problémy s obchodními daty. Pokud stejné číslo partnerské položky způsobuje chybu každý týden, nejde o jednorázový incident, ale o problém s datovým vlastníkem nebo procesem.

Je také vhodné měřit, kolik času uplyne mezi vznikem chyby a jejím vyřešením, kolik obchodních událostí čeká na zpracování a kolikrát je nutný lidský zásah. Tyto ukazatele nepopisují pouze výkon IT. Ukazují, jak předvídatelné je zpracování objednávek, provoz skladu nebo finanční administrativa.

Je třeba se připravit i na chyby v partnerských vztazích

Ne každé API je spojeno s vlastním systémem. Přepravci, poskytovatelé plateb, dodavatelské platformy a zákaznické systémy mohou být také součástí procesu. V takových případech dostupnost, doba odezvy, změna verze a kvalita dat částečně závisí na externím subjektu.

Dobrá architektura proto nestaví na neomezené důvěře. Určuje časové limity, omezuje opakované požadavky na chybného partnera a tam, kde to obchodní proces umožňuje, odděluje okamžitý zákaznický zážitek od zpracování na pozadí. Objednávka může být například interně zaznamenána, i když je přepravní štítek vytvořen až později. Ale to lze udělat pouze tehdy, pokud je jasné, kdo a kdy zkontroluje pozdější splnění.

Sem patří i řízení změn. Změna polí nebo pravidel externího API se dříve či později stane. S verzovanými připojeními, testovacím prostředím a kontrolovaným zaváděním zůstává změna plánovaným úkolem, nikoli pondělním ranním výpadkem.

Dobrý systém zpracování chyb API nakonec neslibuje, že k chybám nikdy nedojde. Zajišťuje, že v případě chyby je stav obchodního procesu znám, další krok je jasný a organizace se nespoléhá na rutinu jednoho člověka nebo ruční tabulky. Odtud stojí za to přemýšlet dál: u kterého současného systémového propojení byste dnes nedokázali prokázat, co se stalo po neúspěšném přenosu dat?