Propojení začíná významem dat
Dvě API mohou používat stejné slovo a myslet jím jinou skutečnost. „Zákazník“ může být osoba, smluvní strana nebo účet; „aktivní“ může znamenat schválený, zaplacený či pouze nevypnutý. Technický převod formátu pak nemusí zachovat obchodní význam. První krok integrace je společný slovník a mapa stavů: odkud údaj pochází, kdo jej mění, kdy nabývá platnosti a jak se pozná, že je zastaralý.
Mapa toku má zahrnout také člověka, který řeší výjimky. U každého důležitého pole se určí zdroj pravdy, pravidlo synchronizace a postup při konfliktu. Teprve potom se volí rozhraní. Někdy stačí synchronní dotaz, jindy se hodí událost nebo dávka. Správná volba závisí na toleranci zpoždění, dostupnosti partnera, objemu a nákladech na opravu. Architektura, která tyto podmínky nepojmenuje, snadno přesune ruční práci na provozní tým.
Kontrakt je víc než seznam polí
Rozhraní má popsat nejen syntaxi, ale také význam hodnot, povolené změny stavu, chybové odpovědi, verzování, časové pásmo, identifikátory a limity. U synchronního API je důležité stanovit, jak dlouho se čeká, kdy lze volání zopakovat a co znamená timeout. U událostí se určuje, zda mohou přijít duplicitně, v jiném pořadí nebo po změně schématu. Odpovědnosti za tyto změny musí být dohodnuté mezi vlastníky systémů.
OpenAPI poskytuje strojově čitelný popis HTTP rozhraní; AsyncAPI pomáhá popisovat rozhraní založená na zprávách a událostech. Specifikace sama o sobě ale nevysvětlí každé obchodní pravidlo ani nezaručí, že druhá strana dodržuje očekávání. Vhodným doplňkem jsou ukázkové případy, kontraktové testy a záznam rozhodnutí o významu polí. Při změně API má tým vědět, které spotřebitele ovlivní a jak bezpečně projít přechodným obdobím.
Synchronní, asynchronní a dávkové toky
Synchronní volání dává rychlou odpověď, ale přenáší nedostupnost druhého systému do uživatelské cesty. Asynchronní zpráva oddělí časy obou stran, zároveň přidá potřebu sledovat frontu, opakování a konečný výsledek. Dávka může být jednoduchá pro velký přenos, pokud je přijatelná aktualizace s odstupem. Jeden produkt může použít všechny tři způsoby pro různé úlohy. Důležité je, aby uživatel i provoz rozuměli čerstvosti a jistotě zobrazeného stavu.
Příklad: klientský portál může potřebovat okamžitou kontrolu oprávnění, ale pozdější přenos změny do reportingu. Pokud se reporting opozdí, nesmí se tvářit jako aktuální. Jiný příklad je import historických dat, u něhož lze přenos spustit znovu, ale výsledek musí být reprodukovatelný a bez duplicit. Volba mechanismu se dělá podle konkrétního dopadu, nikoli podle preference frameworku. Časové okno, stav zpracování a možnost nápravy mají být součástí zadání.
Idempotence, pořadí a neznámý výsledek
Když volající nedostane odpověď, neví automaticky, zda druhá strana požadavek zpracovala. Opakování může být nezbytné, ale přijímač musí poznat, že jde o stejnou operaci. Vzor idempotentního příjemce popisuje identifikaci opakovaných požadavků a vrácení již uloženého výsledku. Pro obchodní systém je třeba navíc určit, co znamená „stejná“ operace, jak dlouho se její identifikátor uchovává a co při změně obsahu požadavku.
Pořadí událostí může být důležité pro stav účtu, ale ne každá infrastruktura jej zaručuje napříč všemi zdroji. Spotřebitel potřebuje pravidlo pro pozdě doručenou zprávu, duplicitní verzi a mezeru v posloupnosti. Někdy je vhodnější získat nový autoritativní stav než slepě přehrávat staré události. Tyto případy se testují na konkrétním doménovém příkladu. Provozní tým musí umět rozeznat, zda se tok pouze opozdil, nebo zda vyžaduje zásah.
Mapování a kvalita dat
Mapovací tabulka vysvětluje zdrojové a cílové pole, transformaci, vlastníka a postup pro nevalidní hodnotu. Nestačí vědět, že se z JSONu vytvoří jiný JSON. Je třeba rozhodnout, co se stane při chybějícím identifikátoru, jiném formátu měny, nečekané časové zóně nebo historickém záznamu s významem, který nový systém nemá. Některé údaje se musí odmítnout a vrátit k opravě, jiné lze bezpečně normalizovat.
Kvalita se měří na celém toku: úplnost, aktuálnost, počet odmítnutých záznamů a podíl ručních oprav. Výchozí stav je důležitý, aby bylo možné poznat, zda integrace proces skutečně zlepšila. Při migraci se ověřuje vzorek reálných anonymizovaných dat a porovnává výsledek se zdrojem. Skryté doplňování hodnot „pro jistotu“ může vytvořit dlouhodobý nesoulad. Každá automatická oprava má mít vysvětlené pravidlo a možnost kontroly.
Pozorovatelnost a provozní oprava
Zdraví integrace není totéž co dostupnost jejího endpointu. Je třeba sledovat stáří poslední úspěšné synchronizace, velikost fronty, chybové stavy, počet opakování a rozdíly proti zdroji pravdy. Stabilní korelační identifikátor umožní dohledat jeden případ bez šíření citlivých údajů do logů. Alarmy mají priority a vlastníky; pro každou významnou chybu existuje postup, co ověřit a zda je bezpečné zprávu zpracovat znovu.
Při incidentu se rozlišuje oprava technického doručení od opravy obchodního stavu. Opakované spuštění celého importu bez pravidel může situaci zhoršit. Provozní rozhraní může nabídnout bezpečný retry konkrétního záznamu, karanténu nevalidního vstupu a záznam lidského rozhodnutí. Takové funkce se nevyvíjejí pro každý tok v plné šíři; vybírají se podle dopadu chyby a objemu výjimek. Podstatné je, aby návrh s opravou počítal od počátku.
První ověřitelná dodávka
Začněte jedním důležitým tokem se skutečným zdrojem a cílem. Definujte kontrakt, mapování, identifikátor, chování při nedostupnosti a měřítko úspěchu. Prototyp má zpracovat správný případ, nevalidní vstup, opakovaný požadavek a timeout. Výsledkem je nejen běžící přenos, ale také přehled chyb a postup, jak zjistit, co se stalo. Tato etapa odhalí skutečné limity API i kvalitu dat dřív než rozsáhlá implementace.
Před odhadem dalších toků získejte dokumentaci partnerů, testovací přístup, anonymizovaný vzorek dat a osoby oprávněné rozhodovat o významu polí. U každé vazby zaznamenejte tolerované zpoždění a vlastníka provozu. Někdy je největší riziko v technologii, jindy v nejasném procesu či smlouvě s poskytovatelem. Plán dodávky má oddělit tyto nejistoty od známé práce a ukázat, co bude klient schvalovat po prvním ověření.
Otázky pro dlouhodobou udržitelnost
Dobrá integrace má být srozumitelná člověku, který ji bude měnit po roce provozu. Potřebuje vědět, proč zvolený tok existuje, kde je zdroj pravdy, jak se pozná chyba a jak se vrátit po neúspěšné změně. Udržitelnost stojí na kontraktu, testech důležitých výjimek a stručném provozním návodu, ne na množství komponent. Pokud odpovědi chybějí, další připojený systém problém násobí.
Před každou změnou je vhodné projít známé spotřebitele a ověřit, zda nový údaj nepoužívají jiným způsobem, než naznačuje technická specifikace. Přechodné období může vyžadovat obě verze kontraktu současně. Ukončení staré verze má mít vlastníka, termín a důkaz, že žádný důležitý tok nezůstal bez podpory. Tato disciplína omezuje počet nečekaných výpadků při běžné evoluci produktu.
- Kdo vlastní význam a změnu každého důležitého údaje?
- Kdy je přijatelný opožděný stav a jak se označí uživateli?
- Co se stane při opakovaném, chybějícím nebo pozdním záznamu?
- Jak se ověří, že se data po migraci významově shodují?
- Který tým reaguje na nesoulad a jak jej opraví bez ztráty historie?
- Jak se projeví změna kontraktu u všech známých spotřebitelů?
- Má integrace měřítko kvality, které vede ke konkrétnímu rozhodnutí?