API integracija je pouzdana tek kada tim može objasniti što se događa s poslovnim događajem nakon timeouta, ponovljenog zahtjeva ili promjene vanjskog sustava. To zahtijeva ugovor koji opisuje ponašanje, idempotency za promjene stanja, ograničen retry, vidljiv red za oporavak i verzioniranje API-ja s planom migracije. HTTP 200 sam po sebi nije dokaz da je narudžba, dokument ili drugi poslovni rezultat stvarno dovršen.
API koji uredno vrati prvi odgovor još nije pouzdana integracija. Pravi test dolazi kada poruka stigne dvaput, vanjski sustav promijeni polje, poziv traje predugo ili odgovor potvrdi prihvat zahtjeva koji kasnije nije obrađen.
Stabilnost se gradi u ugovoru i ponašanju pri pogrešci, ne u idealnom primjeru iz dokumentacije. To je posebno važno kada ERP razmjenjuje narudžbe, zalihe, račune ili statuse s drugim sustavima. Tehnička nejasnoća tada brzo postaje poslovni problem: dupli dokument, nepoznat status narudžbe ili ručna provjera bez jasnog traga.
Schema određuje koja polja postoje. Integracijski ugovor treba objasniti što ona znače, kada su obvezna, tko ih smije promijeniti i što odredišni sustav radi nakon primitka poruke.
Za svaki endpoint zapišite:
Dokumentacija treba sadržavati negativne primjere. Programeru je često korisnije vidjeti odbijeni zahtjev zbog neispravnog podatka, nedostatne ovlasti ili konflikta stanja nego još jedan savršeni odgovor. Poslovni vlasnik pritom može potvrditi odgovara li povratna informacija stvarnoj odluci koju korisnik mora donijeti.
Dobar ugovor također razlikuje sinkronu potvrdu primitka od potvrde poslovnog ishoda. Ako API vrati da je zahtjev prihvaćen za obradu, klijent mora znati gdje i kada provjerava je li nastao konačni dokument ili status.
Kada klijent ne dobije odgovor, ne zna je li zahtjev propao ili je obrada završila bez potvrde. Prirodna reakcija je ponoviti poziv. Bez idempotency pravila takav retry može stvoriti duple narudžbe, dokumente ili naplate.
Za operacije koje mijenjaju stanje koristite stabilan identifikator zahtjeva, vezan uz istu poslovnu namjeru. Odredište treba moći prepoznati da je isti zahtjev već obrađen i pri sigurnom ponavljanju vratiti isti rezultat ili jasan pokazatelj prethodne obrade.
Primjer je slanje narudžbe iz web trgovine u ERP. Ako web trgovina nakon timeouta ponovno pošalje istu narudžbu, ERP ne smije otvoriti novu narudžbu samo zato što je stigao novi HTTP poziv. Identifikator zahtjeva mora ostati isti kroz pokušaje, a zapis obrade mora biti dostupan dovoljno dugo da pokrije očekivani obrazac ponavljanja.
Nisu sve radnje jednako pogodne za automatsko ponavljanje. Ako se idempotency ne može provesti, dokumentacija mora jasno navesti ograničenje, način provjere prethodnog stanja i odgovornu ulogu koja donosi odluku prije ponovnog slanja.
Automatsko ponavljanje pomaže kod kratkog prekida, ali bez granice može pojačati problem. Velik broj klijenata koji odmah ponovi zahtjev dodatno opterećuje sustav koji se već oporavlja.
Retry politika treba definirati:
Pogrešku zbog neispravnog podatka ne treba automatski ponavljati. Ona traži ispravak podatka ili poslovnu odluku. Isto vrijedi za nedostatne ovlasti i zahtjeve koji krše objavljeno pravilo procesa.
Neobrađena poruka mora završiti u vidljivom redu za oporavak, s razlogom, poslovnim kontekstom i mogućnošću kontroliranog ponavljanja. Red nije mjesto na koje poruka nestaje. On je radni popis za osobu ili tim koji može utvrditi treba li podatak popraviti, ponovno poslati događaj ili zaustaviti daljnju obradu.
Promjena naziva polja ili semantike statusa može biti mala u jednom sustavu, a skupa u deset integracija. Kompatibilne promjene treba dodavati bez rušenja postojećih klijenata. Prekidne promjene zahtijevaju novu verziju, objavljenu razliku u ponašanju i jasno razdoblje migracije.
API management nije samo objava endpointa. Uključuje evidenciju o tome tko koristi koju verziju, pravila depreciranja, komunikaciju promjena i nadzor stvarnog prometa. Bez te evidencije stara verzija ne može sigurno završiti, a nova se razvija pod pritiskom nepoznatih ovisnosti.
Prije prekidne promjene tim treba odgovoriti na nekoliko pitanja:
HTTP 200 govori da je poziv prihvaćen, ne nužno da je poslovni proces završen. Za praćenje cijelog toka koristite korelacijski identifikator kroz izvorni sustav, red poruka, servis i odredišni dokument. Tako se jedan zahtjev može povezati s konkretnom narudžbom ili računom, bez oslanjanja na vrijeme poziva i nagađanje.
Operativni pregled treba pokazati broj neuspjelih obrada, starost najstarije poruke, trajanje cijelog toka i predmete koji čekaju ručni oporavak. Tehnička metrika bez poslovnog predmeta otežava razgovor s korisnikom koji želi znati je li narudžba obrađena, a ne samo je li servis odgovorio.
Prije produkcije namjerno izazovite spor odgovor, timeout, privremenu nedostupnost, neispravan token, promijenjenu schemu i dupli zahtjev. Cilj nije dokazati da API može pasti. Cilj je provjeriti pada li ostatak procesa kontrolirano i ostavlja li dovoljno podataka za oporavak.
Consumer-driven contract testovi mogu rano otkriti promjenu ponašanja pružatelja koja ruši klijenta. Sandbox pomaže integratoru, ali mora dovoljno vjerno opisivati produkcijske kodove pogrešaka, ograničenja i podatkovna pravila. Sandbox koji prihvaća sve zahtjeve ne priprema tim za stvarnu odluku pri pogrešci.
Za kritične veze pripremite operativni runbook. On treba odgovoriti gdje se vidi stanje poruke, kako se zaustavlja nekontrolirani retry, tko smije ponovno poslati poruku i kako se potvrđuje konačni poslovni rezultat. Neka runbook isproba osoba koja nije pisala integraciju. Ako ga samo autor može slijediti, znanje još nije dio sustava.
Kada više poslovnih modula razmjenjuje podatke, ugovor integracije treba povezati s vlasništvom nad procesom, a ne ostati samo tehnički dokument. U tom razgovoru pomaže pregled Poslovni moduli povezani s ERP-om , posebno kada treba odrediti gdje nastaje izvorni događaj i tko potvrđuje završni rezultat.
API integracija postaje pouzdana kada su uspjeh, kašnjenje i pogreška jednako dobro dizajnirani. Kao sljedeći korak, odaberite jedan kritični tok, primjerice narudžbu do ERP dokumenta, i prođite ga s timom od timeouta do ručnog oporavka. Ako ne možete pokazati identifikator zahtjeva, verziju ugovora, stanje u redu i potvrđeni poslovni ishod, dovršite te dijelove prije nego što veza postane kritična za svakodnevni rad.