API · INTEGRATIONS · RELIABILITY · 11 MIN ČITANJA
Pouzdana integracija nije skripta koja radi na demo podacima, nego proizvodni tok koji zna prepoznati, zabilježiti i oporaviti grešku.
Prvo odredite vlasništvo nad podacima
Za svaki entitet treba postojati autoritativni sustav. Jedan sustav može biti vlasnik gosta, drugi rezervacije, treći financijskog dokumenta. Ako oba kraja slobodno mijenjaju isto polje, sinkronizacija postaje natjecanje u kojem zadnji zapis pobjeđuje bez poslovnog razloga.
Dogovorite smjer, identifikatore i pravila mapiranja prije pisanja koda. Posebno dokumentirajte vrijednosti koje ne postoje na obje strane i način na koji se tretiraju nepoznati statusi.
Svaka važna operacija treba biti idempotentna
Mreža može prekinuti odgovor nakon što je druga strana već obradila zahtjev. Pošiljatelj tada ne zna je li operacija uspjela i mora pokušati ponovno. Ako ponovno slanje stvori novu rezervaciju ili naplatu, integracija nije sigurna.
Idempotency ključ, vanjski identifikator i evidencija obrađenih događaja omogućuju da isti zahtjev bude prepoznat i vrati postojeći rezultat. To je ključno za rezervacije, plaćanja, račune i promjene inventara.
Retry bez idempotencije nije mehanizam pouzdanosti; to je mogućnost dupliciranja poslovnog događaja.
Ne mora sve biti sinkrono
Korisnik ne treba čekati da pet vanjskih servisa potvrdi interni zapis. Često je bolje spremiti osnovnu transakciju, objaviti događaj i povezane korake obraditi u pozadini. Red poruka čuva posao dok je vanjski sustav nedostupan.
Sinkroni poziv koristite kada je odgovor nužan za sljedeću korisničku odluku, primjerice završna potvrda dostupnosti. Za obavijesti, CRM sinkronizaciju ili analitiku asinkroni tok smanjuje vezanost sustava.
Retry treba imati granice
Privremene greške zaslužuju ponavljanje s rastućim odmakom. Validacijska greška, nepoznata jedinica ili odbijena autorizacija neće nestati nakon deset identičnih pokušaja. Integracija mora razlikovati prolazne i trajne greške.
Nakon određenog broja pokušaja poruka prelazi u kontrolirani red za obradu grešaka. Tamo treba sadržavati dovoljno konteksta da osoba razumije problem i nakon ispravka ponovno pokrene obradu.
Log nije dovoljan bez poslovnog konteksta
Tehnički zapis “HTTP 400” rijetko pomaže operativi. Potrebno je povezati grešku s rezervacijom, objektom, kanalom i konkretnim korakom. Dashboard treba pokazati broj uspješnih i neuspješnih poruka, kašnjenje reda i ponavljajuće uzroke.
Korelacijski identifikator kroz sve servise skraćuje dijagnostiku. Osjetljivi podaci i vjerodajnice pritom se ne smiju zapisivati u logove.
API ugovor se mijenja
Vanjski sustav može dodati status, promijeniti ograničenje ili ugasiti verziju endpointa. Integracija treba tolerirati nepoznata dodatna polja, ali jasno reagirati kada nedostaje obvezan podatak. Contract testovi i testno okruženje pomažu otkriti promjenu prije produkcije.
Verzije, rokovi i vlasnik integracije trebaju biti dokumentirani. “Jednom spojeno” ne znači trajno završeno; API integracija je odnos dvaju proizvoda koji se razvijaju različitim tempom.
Minimalni produkcijski checklist
Prije puštanja provjerite autentikaciju i rotaciju tajni, timeoute, retry pravila, idempotenciju, rate limits, mapiranje identifikatora, audit, alarme i ručni oporavak. Testirajte duplikate, poruke izvan redoslijeda i nedostupan vanjski servis, ne samo idealan tok.
Integracija je uspješna kada tim više ne prepisuje podatke, a iznimke su rjeđe i vidljivije. Ako je za svakodnevni rad potrebna nova tablica “da pratimo što se nije prenijelo”, sustav još nije dovršen.