Ako navrhnúť spoľahlivé API chybové spracovanie

Objednávka z e-shopu dorazí, ale systém správy zásob práve nereaguje. Zákazník dostane potvrdenie, ale objednávka sa nezobrazí na zozname úloh skladu. O dve hodiny neskôr sa kolega pokúša zistiť informácie z tabuľky a ručne zaznamenáva údaje. Toto nie je jednoduchá technická chyba: môže viesť k rozdielom v zásobách, oneskorenému doručeniu, nesprávnemu fakturovaniu a strate dôvery. Preto otázka nie je len o tom, ako navrhnúť spracovanie chýb API, ale aj o tom, ako udržať obchodný proces pod kontrolou v prípade systémovej chyby.

API zvyčajne znamenajú spojenie medzi systémami. Spájajú e-shop s ERP, dopravnou službou, fakturačným systémom, systémom pre správu vzťahov so zákazníkmi alebo výrobnou aplikáciou. Pokiaľ sú všetky odpovede rýchle a úspešné, toto spojenie je neviditeľné. V prípade chyby sa však ukáže, či sa informácia skutočne preniesla, kto je zodpovedný za ďalší krok a či existuje spôsob, ako bezpečne pokračovať v práci.

Spracovanie chýb začína obchodnými dôsledkami

Prvou chybou v mnohých organizáciách je, že všetky neúspešné API volania sú považované za rovnakú kategóriu. Ale je podstatný rozdiel medzi tým, keď kuriérska služba nie je dostupná na päť sekúnd, keď sa pripájame k systému partnera s nesprávnym identifikátorom, alebo keď v objednávke chýba poštové smerovacie číslo.

Technická správa sama o sebe zriedka pomôže operačnému tímu. „400 Bad Request“ nepovie, či je možné objednávku opraviť, znovu odoslať alebo či je potrebné konzultovať so zákazníkom. „500 Internal Server Error“ neodpovie, či sa objednávka stratila, čaká na spracovanie alebo už bola vytvorená v cieľovom systéme, len odpoveď sa stratila.

Predtým, než napíšeme pravidlá pre vývoj, je vhodné prejsť si proces pre každú dôležitú integráciu. Čo spúšťa prenos údajov? Ktorý systém je vlastníkom údajov? Čo sa stane, ak prenos zlyhá? Kto to vidí, v akom termíne a ako je možné overiť opravu? Objednávka, faktúra alebo výrobný príkaz sa nemôže stať „neistým stavom“ údajov len preto, že medzi dvoma systémami došlo k dočasnému komunikačnému výpadku.

Ako navrhnúť spracovanie chýb API podľa procesu?

Dobrý návrh nezačína jediným všeobecným zoznamom chýb, ale identifikáciou kritických obchodných udalostí. Prenos objednávky z e-shopu vyžaduje inú ochranu ako synchronizácia obrázka produktu. Pri vytváraní faktúry alebo rezervácii výrobného zásobovania môže jediná duplikovaná požiadavka spôsobiť finančné alebo operačné problémy. Aktualizácia dennej správy zvyčajne znesie niekoľko minút oneskorenia, pokiaľ zostane presnosť údajov zachovaná.

Pri každom procese je užitočné položiť si tri otázky:

1. Aký je obchodný dopad chyby, ak údaje neprejdú včas?
2. Je možné operáciu zopakovať bez škodlivých vedľajších účinkov?
3. Kedy je potrebné ľudské rozhodnutie a kedy je možné situáciu automaticky opraviť?

Na základe odpovedí na tieto otázky je možné vytvoriť primerané spracovanie chýb. Nie každá chyba vyžaduje okamžité upozornenie. Ak nejaká nekrízová aktualizácia údajov dorazí s trojminútovým oneskorením, neustále telefonické upozornenia skôr vytvárajú hluk. Ak však kvôli neúspešnej rezervácii zásob e-shop predáva produkt, ktorý už nie je na sklade, je potrebné okamžité a jednoznačné riešenie.

Majte jasné typy chýb

Chyby je vhodné kategorizovať nielen podľa HTTP kódov, ale aj podľa spôsobu spracovania. Medzi dočasné chyby patrí napríklad prerušenie siete, preťažený partnerský systém alebo vypršaný časový limit. V týchto prípadoch je opakovaný pokus zvyčajne oprávnený. Trvalé chyby, ako sú nesprávne oprávnenia alebo zmenené API spojenie, sa opakovaním nevyriešia. Tu je potrebný technický zásah.

Tretia skupina sú chyby obchodných údajov alebo pravidiel. Môže ísť o chýbajúce daňové číslo, neexistujúce číslo položky, uzavretý stav objednávky alebo nepovolenú zľavu. Systémy musia tieto chyby jasne komunikovať zodpovednému pracovníkovi: čo je potrebné opraviť, kde a čo sa stane po oprave.

Toto rozlišovanie chráni tím pred tým, aby rovnakú chybnú objednávku posielal stokrát znova, zatiaľ čo iný, dočasne neúspešný prenos údajov sa nepozorovane stratí medzi dennými úlohami.

Opakovanie musí mať hranice a pravidlá

Opakovanie API požiadavky sa môže zdať ako samozrejmé riešenie, ale nie vždy je bezpečné. Ak systém úspešne vytvoril faktúru a potom sa spojenie prerušilo pred odpoveďou, opakovaná požiadavka môže vytvoriť druhú faktúru. To isté sa môže stať pri zaznamenávaní objednávky, žiadosti o platbu alebo generovaní prepravného štítku.

Preto je pre kritické operácie potrebný jedinečný identifikátor. Prijímajúci systém musí rozpoznať, že ide o opakovanú požiadavku na tú istú obchodnú udalosť a nesmie ju vykonať znova. Toto sa nazýva idempotentná operácia. Z pohľadu manažmentu je to jednoduché: dočasná chyba by nemala viesť k dvojnásobným finančným, skladovým alebo zákazníckym operáciám.

Časovanie opakovaní musí byť tiež regulované. Niekoľkosekundové, postupne sa predlžujúce čakanie je v mnohých prípadoch vhodné. Neustále, okamžité opakovanie však môže ďalej zaťažovať chybný systém a zakrývať skutočný problém. Po určenom počte pokusov by sa prípad mal presunúť na kontrolovateľný zoznam čakajúcich, aby sa nestratil v log súboroch.

Nenechávajte kolegu ako riešiteľa chýb medzi systémami

V mnohých firmách je spracovanie chýb integrácie v skutočnosti v hlave skúseného pracovníka. Vie, ktorý e-mail hľadať, v ktorom systéme reštartovať operáciu a ktoré údaje manuálne upraviť. To sa môže zdať ako rýchle riešenie, ale vytvára proces závislý na osobe. Pri dovolenke, chorobe alebo raste sa to okamžite stáva rizikom.

Spravovateľný systém nenechá užívateľa osamoteného s technickou chybovou správou. Zodpovedná rola potrebuje pracovný zoznam, v ktorom je viditeľný dotknutý obchodný objekt - napríklad identifikátor objednávky, partner alebo faktúra -, príčina chyby, doterajšie pokusy a ďalší odporúčaný krok. Po oprave chyby by mal byť proces pokračovateľný podľa pravidiel, pokiaľ možno bez ručného kopírovania údajov.

To neznamená, že všetky výnimky musia byť automatizované. Dodacie podmienky objednávky významného zákazníka alebo neobvyklá výrobná položka môžu vyžadovať skutočné ľudské posúdenie. Cieľom je, aby kolega robil rozhodnutia, nie lovil údaje medzi systémami a zadával rovnaké informácie na viacerých miestach.

Protokolovanie a sledovateľnosť: potrebný je dôkaz, nie predpoklad

Keď sa manažér opýta, „prešla táto objednávka?“, systém musí poskytnúť jednoznačnú odpoveď. Na to je potrebný sledovateľný identifikátor, časová pečiatka, výsledok požiadavky, stav spracovania a - kde je to vhodné - podrobný dôvod chyby pre každú dôležitú API operáciu. Osobné, platobné alebo iné citlivé údaje samozrejme nesmú byť nekontrolovane protokolované.

Protokol však sám o sebe nie je prevádzkový model. Je potrebné sledovať pomer neúspešných volaní, dĺžku spracovateľských radov, zhoršovanie časov odozvy a opakujúce sa problémy s obchodnými údajmi. Ak rovnaké číslo partnerskej položky spôsobuje chybu každý týždeň, nejde o jednorazový incident, ale o problém s vlastníkom údajov alebo procesom.

Je tiež vhodné merať, koľko času uplynie medzi vznikom chyby a jej vyriešením, koľko obchodných udalostí čaká na spracovanie a koľkokrát je potrebný ľudský zásah. Tieto ukazovatele nepopisujú len výkon IT. Ukazujú, ako predvídateľné je spracovanie objednávok, prevádzka skladu alebo finančná administratíva.

Je potrebné pripraviť sa aj na chyby partnerských vzťahov

Nie každé API je pripojené k vlastnému systému. Dopravcovia, poskytovatelia platobných služieb, dodávateľské platformy a zákaznícke systémy môžu byť súčasťou procesu. V takýchto prípadoch dostupnosť, čas odozvy, zmena verzie a kvalita údajov čiastočne závisia od externého subjektu.

Dobrý architektonický návrh preto nestavia na neobmedzenej dôvere. Definuje časové limity, obmedzuje opakované požiadavky na chybný partner a tam, kde to obchodný proces umožňuje, oddelí okamžitú zákaznícku skúsenosť od spracovania na pozadí. Objednávka môže byť napríklad zaznamenaná interne, aj keď sa prepravný štítok vytvorí až neskôr. Ale to by sa malo urobiť len vtedy, keď je jasné, kto a kedy skontroluje neskoršie splnenie.

Sem patrí aj riadenie zmien. Zmena polí alebo pravidiel externého API sa skôr či neskôr stane. S verzionovanými spojeniami, testovacím prostredím a kontrolovaným zavedením zostáva zmena plánovanou úlohou, nie pondelkovým ranným výpadkom.

Dobrý systém spracovania chýb API nakoniec nesľubuje, že sa chyba nikdy nestane. Zaisťuje, že v prípade chyby zostane stav obchodného procesu známy, ďalší krok bude jasný a organizácia sa nebude spoliehať na rutinu jedného človeka alebo ručné tabuľky. Odtiaľto je vhodné premýšľať ďalej: pri ktorom súčasnom systéme by ste dnes nevedeli dokázať, čo sa stalo po neúspešnom prenose údajov?