Integrace začíná významem dat
Když dva systémy umějí poslat JSON přes HTTP, ještě to neznamená, že si rozumějí. Jeden může pojmem zákazník myslet osobu s platnou smlouvou, druhý jakýkoli kontakt v databázi. Jeden zaznamenává čas vytvoření požadavku, druhý čas jeho schválení. Takové rozdíly zpočátku vypadají jako drobnosti v mapování polí. V provozu ale vytvářejí duplicitní záznamy, nesprávné stavy a spory o to, kde se chyba vlastně stala. Návrh proto začněte slovníkem obchodních pojmů a několika skutečnými příklady, ne seznamem endpointů.
U každého údaje určete zdroj pravdy, povolené změny a vlastníka opravy. Pokud CRM zakládá klienta a fakturační systém spravuje jeho platební stav, nesmí obě aplikace samostatně rozhodovat o stejném poli bez pravidla řešení konfliktu. Zachyťte také časovou platnost: kdy je změna považována za dokončenou a jak staré údaje ještě smí čtenář vidět. Teprve pak má smysl zvolit přenosový mechanismus. Výsledkem této fáze může být krátká tabulka pojmů, vlastnictví a událostí; její hodnota je v přesnosti, ne v rozsahu.
Vyberte hranici, která odpovídá práci uživatele
Synchronní volání se hodí, když uživatel potřebuje odpověď hned a přijatelné čekání je jasné. Asynchronní zpráva dává smysl, když zpracování může chvíli trvat, je třeba vyrovnávat nárazovou zátěž nebo cílový systém občas neběží. Rozhodnutí není soutěží technologií. Podívejte se na konkrétní cestu: co má obrazovka potvrdit, co může zůstat ve stavu „zpracovává se“ a jak se uživatel dozví konečný výsledek. Není poctivé zobrazit „hotovo“, pokud pouze prošel první požadavek.
Oddělte operaci, která mění stav, od dotazu, který jen čte. Zapište, zda volající očekává okamžitou konzistenci, nebo mu stačí stav aktualizovaný později. Při asynchronním toku musí být zřejmé, jak se spojí přijatá zpráva s původním požadavkem a jak se opraví zpráva, která selhala opakovaně. Pro malý projekt často stačí dobře navržené API a jednoduchá fronta; složitá platforma sama o sobě žádný nejasný obchodní proces nevyřeší.
Kontrakt popisuje i chyby a změny
Kontrakt API není jen seznam polí v úspěšné odpovědi. Musí popsat povinná a volitelná data, formát identifikátorů, pravidla stránkování, oprávnění, chybové kódy a význam jednotlivých stavů. Specifikace OpenAPI umožňuje popsat operace, schémata i callbacky a webhooky. Použijte ji jako společný artefakt pro klienta, dodavatele a testy. Samotný soubor však nenahradí příklady situací, v nichž se obchodní význam liší podle kontextu.
Každá změna kontraktu má spotřebitele. Přidání volitelného pole bývá snazší než změna významu existujícího pole, ale ani první případ není automaticky bezpečný pro všechny klienty. U zpráv je třeba znát pravidla kompatibility schémat v obou směrech a délku přechodného období. Dokumentace Confluent Schema Registry rozlišuje kompatibilitu backward, forward, full a transitive; konkrétní volba závisí na tom, kdo nasazuje první a jak dlouho se uchovávají staré zprávy. V praxi testujte nový kontrakt proti reálným konzumentům, ne pouze proti syntaxi schématu.
Neznámý výsledek není totéž co neúspěch
Nejnebezpečnější integrační situace nastává, když volající pošle příkaz, ale nedostane odpověď. Cílový systém mohl operaci provést a odpověď se ztratila. Při slepém opakování může vzniknout druhá platba, objednávka nebo účet. U operací měnících stav proto navrhněte idempotentní klíč nebo jiný jednoznačný způsob rozpoznání opakovaného požadavku. Stejný logický příkaz musí při opakování vrátit informaci o již známém výsledku, nikoli znovu spustit vedlejší účinek.
Opakování používejte jen pro přechodné chyby a s omezeným počtem pokusů. AWS v dokumentaci vzoru retry with backoff upozorňuje na idempotenci, riziko zatížení při masových opakováních a rozdíl mezi dočasnou a trvalou chybou. Praktický návrh musí odpovědět, kdo znovu zkusí požadavek, jak dlouho, s jakým odstupem a kdy se věc předá člověku. Pro trvale chybné údaje je další automatický pokus zbytečný. Potřebujete viditelný stav, důvod odmítnutí a bezpečný postup opravy.
Naplánujte návrat z částečného dokončení
Přes více nezávislých systémů obvykle nedostanete jednu společnou databázovou transakci. Představte si založení klienta v CRM, vytvoření smlouvy a následné založení fakturačního profilu. První dvě akce mohou proběhnout a třetí selhat. Návrh musí říci, zda se první kroky kompenzují, dokončí později, nebo zůstanou jako explicitní rozpracovaný stav. Každá varianta má náklady a obchodní důsledky; univerzální recept neexistuje.
Sepište několik konkrétních scénářů selhání na hranici kroků a u každého určete vlastníka rozhodnutí. Kompenzační akce není automaticky přesný opak původní operace: odeslaný e-mail nelze „ododeslat“ a zaúčtovaná platba může vyžadovat samostatný proces vrácení. Pokud je nutný ruční zásah, administrátor potřebuje vidět původní požadavek, všechny pokusy a bezpečné dostupné akce. Tato práce se vyplatí provést před implementací, protože později zásadně ovlivní datový model i uživatelské rozhraní.
Bezpečnost je vlastnost toku
Integrace často přenáší citlivá data mezi týmy nebo dodavateli. Nepředpokládejte, že interní síť sama určuje důvěru. Pro každé spojení stanovte identitu volajícího, rozsah oprávnění, způsob rotace klíčů a pravidla pro logování. Princip minimálních oprávnění má konkrétní podobu: služba, která čte stav objednávky, nemá mít právo měnit bankovní údaje. Při webhooku ověřujte původ a podpis zprávy podle skutečného protokolu poskytovatele a zvažte ochranu proti opakovanému doručení.
Do aplikačních logů neposílejte celé tokeny, osobní údaje ani obsah platebních instrukcí. Pro diagnostiku stačí korelační identifikátor, čas, název kroku, typ chyby a bezpečně zvolená metadata. Přenos a uložení dat posuzujte podle jejich citlivosti. Právní požadavky závisí na skutečném účelu a místě zpracování; technický tým má připravit přehled toků a přístupů, aby jej bylo možné kvalifikovaně posoudit. Kvalitní bezpečnostní návrh tedy vzniká společně s mapou procesu, nikoli až po dokončení endpointů.
Provoz potřebuje vysvětlit stav
Metrika „API odpovídá“ nestačí, pokud se obchodní operace ztrácí mezi kroky. Sledujte alespoň počet přijatých a dokončených požadavků, stáří nejstarší nerozpracované položky, podíl oprav, chybovost podle integrace a rozdíl mezi očekávaným a skutečným počtem záznamů. Tyto údaje mají mít vlastníka a hranici, při níž se někdo skutečně podívá na problém. Bez toho je dashboard jen dekorace. Zvlášť důležité je rozlišit technické odmítnutí od obchodního výsledku, například zamítnuté žádosti.
Každý tok musí být dohledatelný od uživatelského požadavku až po poslední krok. Korelační identifikátor pomáhá, ale diagnózu často urychlí i přehled stavových přechodů a verzí kontraktu. Provozní postup má říci, jak pozastavit odesílání, jak znovu zpracovat bezpečnou položku, jak ověřit shodu dat a komu eskalovat chybu u partnera. Postup otestujte na cvičné chybě. Pokud jej tým dokáže provést pouze za účasti původního vývojáře, integrace ještě není připravena k předání.
Ověřte tok na skutečných případech
Test úspěšného požadavku pokrývá nejjednodušší část. Přidejte duplicitní doručení, vypršení časového limitu po úspěšné operaci, starou verzi zprávy, chybějící povinný údaj, nesprávné oprávnění a částečné dokončení. Testujte také migraci či opětovné zpracování starších záznamů. Výsledek každého testu musí být vidět nejen v odpovědi API, ale i v databázi, uživatelském stavu a provozním záznamu. Tam se často odhalí skutečná nekonzistence.
Před spuštěním proveďte omezený pilot s reprezentativními daty a předem připraveným návratem. Dohodněte, kdo potvrdí obchodní správnost a kdo zkontroluje technické metriky. Dokumentujte známá omezení, nejasné stavy a postup jejich řešení. Dobrá integrační architektura neslibuje nulové chyby. Umožňuje chybu zachytit, správně vysvětlit, bezpečně opravit a bez ztráty významu pokračovat v práci.
Po pilotu sledujte první týdny nejen počet chyb, ale i množství ručních oprav a dotazů od lidí, kteří systém používají. Právě jejich otázky odhalují stavy, které jsou technicky platné, ale v rozhraní nepochopitelné. Každou opravu popište tak, aby šla zopakovat bez znalosti původního vývoje. Pokud se určitý incident opakuje, převeďte provozní postup do produktu: srozumitelnější stav, automatické upozornění nebo bezpečné tlačítko pro opakování. Po změně znovu ověřte soulad dat na obou stranách. Integrace se totiž neučí jen z výpadků; také z běžných případů, u nichž lidé potřebují dodatečné vysvětlení. Pravidelná kontrola těchto signálů je levnější než velká jednorázová oprava neviditelného dluhu.