Како поуздано планирати обраду грешака у API-ју

Porudžbina iz internet prodavnice stiže, ali sistem za upravljanje zalihama trenutno ne odgovara. Klijent dobija potvrdu, ali porudžbina se ne pojavljuje na listi zadataka skladišta. Dva sata kasnije, kolega pokušava da dešifruje ovo iz tabele i ručno unosi podatke. Ovo nije jednostavna tehnička greška: može dovesti do razlika u zalihama, kašnjenja u isporuci, pogrešnog fakturisanja i gubitka poverenja. Zato pitanje nije samo kako dizajnirati API za rukovanje greškama, već i kako zadržati kontrolu nad poslovnim procesom u slučaju sistemske greške.

API-jevi obično predstavljaju vezu između sistema. Povezuju internet prodavnicu sa ERP-om, uslugama transporta, fakturisanjem, sistemom za odnose sa klijentima ili aplikacijom za proizvodnju. Dok su svi odgovori brzi i uspešni, ova veza je nevidljiva. U slučaju greške, međutim, postaje jasno da li su informacije zaista prenete, ko je odgovoran za sledeći korak i da li postoji način da se posao sigurno nastavi.

Rukovanje greškama počinje sa poslovnim posledicama

Prva greška kod mnogih organizacija je što tretiraju svaki neuspešan API poziv kao istu kategoriju. Međutim, postoji značajna razlika između toga da li kurirska služba nije dostupna pet sekundi, da li se povezujemo sa sistemom partnera sa pogrešnim identifikatorom ili da li nedostaje poštanski broj u porudžbini.

Tehnička poruka retko pomaže operativnom timu. „400 Bad Request“ ne govori da li se porudžbina može ispraviti, ponovo poslati ili treba konsultovati klijenta. „500 Internal Server Error“ ne odgovara da li je porudžbina izgubljena, čeka na obradu ili je već kreirana u ciljanom sistemu, samo je odgovor izgubljen.

Pre nego što napišemo pravila za razvoj, vredi proći kroz proces za svaku važnu integraciju. Šta pokreće prenos podataka? Koji sistem je vlasnik podataka? Šta se dešava ako prenos ne uspe? Ko to vidi, u kojem roku, i kako se može proveriti ispravka? Porudžbina, faktura ili proizvodna instrukcija ne smeju postati „nesigurni podaci“ samo zato što je došlo do privremenog komunikacijskog prekida između dva sistema.

Kako dizajnirati API rukovanje greškama po procesu?

Dobar dizajn ne počinje sa jednom opštom listom grešaka, već sa identifikacijom kritičnih poslovnih događaja. Prenos porudžbine iz internet prodavnice zahteva drugačiju zaštitu nego sinhronizacija slike proizvoda. Kod kreiranja fakture ili rezervacije proizvodnog zaliha, jedan duplirani zahtev može izazvati finansijske ili operativne probleme. Ažuriranje dnevnog izveštaja obično može izdržati nekoliko minuta kašnjenja, ako se tačnost podataka zadrži.

Za svaki proces korisno je postaviti tri pitanja:

1. Koji je poslovni uticaj greške ako podaci ne stignu na vreme?
2. Može li se operacija ponoviti bez štetnih posledica?
3. Kada je potrebna ljudska odluka, a kada se situacija može automatski ispraviti?

Na osnovu odgovora na ova pitanja može se razviti proporcionalno rukovanje greškama. Nije svaka greška zahteva trenutnu uzbunu. Ako ne-kritično ažuriranje podataka stigne sa tri minuta kašnjenja, kontinuirano telefonsko obaveštavanje više stvara buku. Međutim, ako neuspešna rezervacija zaliha dovede do prodaje proizvoda koji više nije na skladištu, potrebna je trenutna i jasna reakcija.

Neka tipovi grešaka budu jasni

Greške je korisno grupisati ne samo prema HTTP kodovima, već prema načinu rukovanja. Privremene greške uključuju prekid mreže, preopterećen sistem partnera ili istekao vremenski limit. Kod ovih grešaka ponovni pokušaj je obično opravdan. Trajne greške, kao što su neispravna ovlašćenja ili promenjena API veza, ne rešavaju se ponavljanjem. Ovde je potrebna tehnička intervencija.

Treća grupa su greške u poslovnim podacima ili pravilima. To može biti nedostajući poreski broj, nepostojeći broj artikla, zatvoreno stanje porudžbine ili neodobreni popust. Sistemi moraju jasno obavestiti odgovornog radnika šta treba ispraviti, gde, i šta se dešava nakon ispravke.

Ova razlika štiti tim od ponovnog slanja iste pogrešne porudžbine stotinu puta, dok se druga, privremeno neuspešna razmena podataka neprimetno gubi među dnevnim zadacima.

Ponovni pokušaj treba da ima granicu i pravilo

Ponavljanje API zahteva može izgledati kao očigledno rešenje, ali nije uvek bezbedno. Ako je sistem uspešno kreirao fakturu, ali je veza prekinuta pre nego što je odgovor poslat, ponovljeni zahtev može kreirati drugu fakturu. Isto se može dogoditi kod beleženja porudžbine, zahteva za plaćanje ili generisanja transportne etikete.

Zbog toga je potreban jedinstveni identifikator za kritične operacije. Prijemni sistem mora prepoznati da ponovljeni zahtev dolazi za isti poslovni događaj i ne sme ga ponovo izvršiti. Ovo se naziva idempotentnim radom. Iz perspektive menadžmenta, privremena greška ne bi trebala rezultirati dvostrukim finansijskim, skladišnim ili komunikacijskim operacijama sa klijentima.

Takođe, vreme ponovnog pokušaja treba regulisati. Nekoliko sekundi, a zatim postepeno duže čekanje često je prikladno. Kontinuirano, trenutno ponavljanje može dodatno opteretiti sistem sa greškom i prikriti pravi problem. Nakon određenog broja pokušaja, slučaj treba staviti na proverljivu listu čekanja, a ne da nestane u log fajlovima.

Neka kolega ne bude posrednik za rešavanje grešaka između sistema

U mnogim kompanijama, rukovanje greškama integracije zapravo postoji u glavi iskusnog zaposlenog. On zna koji e-mail treba tražiti, u kojem sistemu ponovo pokrenuti operaciju i koji podatak ručno izmeniti. Ovo izgleda kao brzo rešenje, ali gradi proces zavisan od osobe. U slučaju odsustva, bolesti ili rasta, ovo odmah postaje rizik.

Upravljivi sistem ne ostavlja korisnika samog sa tehničkom porukom o grešci. Odgovorna uloga treba radnu listu u kojoj se vidi relevantni poslovni objekat - na primer, identifikator porudžbine, partner ili faktura -, uzrok greške, dosadašnji pokušaji i sledeći preporučeni korak. Nakon ispravke greške, proces treba da se nastavi pravilno, po mogućstvu bez ručnog kopiranja podataka.

Ovo ne znači da sve izuzetke treba automatizovati. Uslovi isporuke porudžbine važnog klijenta ili neobična proizvodna serija mogu zahtevati pravu ljudsku procenu. Cilj je da kolega donese odluku, a ne da lovi podatke između sistema i unosi iste informacije na više mesta.

Logovanje i praćenje: potrebni su dokazi, ne pretpostavke

Kada menadžer pita, „da li je ova porudžbina prošla?“, sistem mora dati jasan odgovor. Za to je potreban pratljiv identifikator, vremenska oznaka, rezultat zahteva, status obrade i - gde je opravdano - detaljan uzrok greške za svaku važnu API operaciju. Naravno, lične, platne ili druge osetljive podatke ne treba logovati bez kontrole.

Međutim, log sam po sebi nije model operacije. Treba pratiti procenat neuspešnih poziva, dužinu redova za obradu, pogoršanje vremena odgovora i ponavljajuće probleme sa poslovnim podacima. Ako isti broj artikla partnera izaziva grešku svake nedelje, to nije jednokratni incident, već problem sa vlasnikom podataka ili procesom.

Takođe je vredno meriti koliko vremena prolazi između nastanka greške i njenog rešavanja, koliko poslovnih događaja čeka na obradu i koliko puta je potrebna ljudska intervencija. Ovi pokazatelji ne opisuju samo performanse IT-a. Pokazuju koliko je predvidiva obrada porudžbina, rad skladišta ili finansijska administracija.

Takođe se treba pripremiti za greške u partnerskim odnosima

Nisu svi API-jevi povezani sa sopstvenim sistemom. Transportne kompanije, pružaoci platnih usluga, platforme dobavljača i sistemi klijenata takođe mogu biti deo procesa. U tim slučajevima, dostupnost, vreme odgovora, promene verzije i kvalitet podataka delimično zavise od spoljnog učesnika.

Dobra arhitektura zato ne gradi na neograničenom poverenju. Definiše vremenska ograničenja, ograničava ponovljene zahteve ka partneru sa greškom i, gde to poslovni proces dozvoljava, odvaja trenutni korisnički doživljaj od pozadinske obrade. Na primer, porudžbina se može interno zabeležiti čak i ako se transportna etiketa izradi kasnije. Ali to treba učiniti samo ako je jasno ko i kada proverava kasnije ispunjenje.

Upravljanje promenama takođe spada ovde. Promena polja ili pravila spoljnog API-ja pre ili kasnije će se dogoditi. Sa verzionisanim vezama, testnim okruženjem i kontrolisanim uvođenjem, promena ostaje planirani zadatak, a ne prekid rada u ponedeljak ujutro.

Dobar API za rukovanje greškama na kraju ne obećava da se greške nikada neće dogoditi. On osigurava da u slučaju greške, stanje poslovnog procesa ostane poznato, sledeći korak bude jasan, i da organizacija ne zavisi od rutine jedne osobe ili ručnih tabela. Odavde vredi razmisliti dalje: kod koje trenutne veze sistema ne biste mogli danas dokazati šta se dogodilo nakon neuspešnog prenosa podataka?