Klient přiřadí jedné obchodní operaci stabilní idempotentní klíč, server ho naváže na identitu a obsah požadavku, atomicky uloží stav a při opakování vrátí původní výsledek nebo bezpečný konflikt. Návrh otestujte při souběhu, timeoutu a částečném selhání.
Idempotence API znamená, že opakované provedení téže zamýšlené operace nevyvolá další nežádoucí účinek. Je důležitá u objednávky, platby, faktury, rezervace nebo importu kontaktu. Klient může požadavek zopakovat po timeoutu, uživatel může kliknout dvakrát a zprostředkovatel může doručit událost vícekrát, přestože první pokus už uspěl.
Jednoduchá kontrola, zda záznam existuje, nemusí stačit při souběhu nebo částečném selhání. Návrh potřebuje identitu operace, atomické uložení stavu, pravidla pro opakovanou odpověď a bezpečnou opravu. Idempotence neznamená ignorovat každý podobný požadavek; dvě skutečně odlišné objednávky musí zůstat odlišné.
Praktická ukázka: zopakovat dávku bez druhého zápisu
Při hromadných úpravách vlastního webu pracujeme s 200 články. Operace proto musí umět pokračovat po přerušení a rozpoznat již zpracovaný článek. Základem je stabilní identita záznamu, uložený plán a kontrola aktuálního stavu před zápisem. Stejné rozhodování je potřebné i u API integrace objednávek.
Následující příklad je modelový návrh API, nikoli existující objednávkový endpoint Webiant. Klient si vytvoří klíč pro jednu obchodní operaci a při opakování požadavku jej zachová:
POST /orders
Idempotency-Key: objednavka-2026-001
{"external_id":"2026-001","amount_cents":12900,"currency":"EUR"}| Situace | Chování serveru |
|---|---|
| První klíč a nový obsah | Atomicky vytvořit objednávku a uložit odpověď ke klíči |
| Stejný klíč a stejný obsah | Vrátit uložený výsledek bez nové objednávky |
| Stejný klíč, ale jiný obsah | Odmítnout konflikt; například HTTP 409 podle smlouvy API |
| Dva souběžné požadavky | Unikátní databázová podmínka a transakce zabrání dvojímu vytvoření |
Kontrola „nejprve vyhledej, potom vytvoř“ při souběžných požadavcích nestačí. Zápis klíče i obchodní operace musí být chráněn transakcí nebo ekvivalentní atomickou operací. Pokud se odesílá e-mail nebo platební požadavek, je třeba zvlášť ošetřit i tento vedlejší účinek.
Test před předáním integrace
- Pošlete stejný požadavek dvakrát a porovnejte ID výsledku.
- Zopakujte požadavek po simulovaném časovém limitu.
- Pošlete dva stejné požadavky souběžně.
- Změňte obsah při stejném klíči a ověřte dohodnutý konflikt.
- Ověřte, že e-mail, platba nebo záznam v CRM nevznikne dvakrát.
U vlastní integrace si dohodněte také dobu uchovávání klíčů a pravidla opakování. Souvisí s tím mapování údajů mezi systémy.
Pochopte, odkud opakování přichází
HTTP klient často neví, zda timeout nastal před zpracováním, nebo po něm. Opakování je proto přirozená strategie, nikoli chyba. Některé fronty a webhookové mechanismy jsou navrženy pro doručení alespoň jednou, což vědomě připouští duplicitu. Uživatelský dvojklik, návrat v prohlížeči nebo opětovný import vytvářejí další cesty ke stejnému účinku.
Zmapujte operace, u kterých duplicita způsobí obchodní problém. Čtení obvykle nemá stejné riziko jako vytvoření platby. Aktualizace na přesnou hodnotu se chová jinak než příkaz zvýšit množství. Ke každé operaci určete identitu záměru a období, během kterého se opakování považuje za totožné.
Navrhněte stabilní idempotentní klíč
Klíč má vzniknout jednou pro konkrétní obchodní záměr a zůstat stejný při technickém opakování. Nemá se generovat znovu při každém pokusu, jinak server duplicitu nerozpozná. Rozsah klíče svažte s klientem, účtem nebo endpointem, aby se náhodná shoda mezi různými uživateli nestala konfliktem.
Server může uložit otisk významného obsahu a odmítnout stejný klíč s jinými parametry. Chrání tím klienta před omylem, kdy klíč znovu použije pro jinou částku nebo produkt. Nezahrnujte do porovnání hodnoty, které se při každém pokusu přirozeně mění, například technickou časovou značku.
- jeden klíč pro jeden obchodní záměr
- vazba na klienta a typ operace
- kontrola změněného obsahu
- jasná doba uchovávání stavu
Uložte stav a výsledek atomicky
Při prvním přijetí vytvořte záznam operace způsobem, který zabrání dvěma souběžným pracovníkům získat vlastnictví. Jedinečný databázový klíč nebo transakční mechanismus je spolehlivější než oddělené „nejprve zkontroluj a pak vlož“. Stav může rozlišovat přijaté, zpracovávané, úspěšné a neúspěšné operace.
Po úspěchu uchovejte bezpečný výsledek nebo odkaz na vytvořený objekt. Opakovaný požadavek má dostat konzistentní odpověď bez dalšího účinku. U dlouhé práce může server oznámit, že operace pokračuje, a nabídnout stavový endpoint. Neuchovávejte nepotřebný citlivý obsah jen kvůli idempotenci.
Řešte částečný úspěch a pořadí kroků
Operace může uložit objednávku a selhat při odeslání e-mailu nebo u externího API. Rozlišujte hlavní obchodní závazek od navazujících úloh. Vedlejší kroky zpracujte přes odolnou frontu a také jim přiřaďte vlastní identitu. Zrušení celého výsledku nemusí být po přijaté platbě možné ani správné.
Pokud stejný objekt mění více událostí, idempotence sama nevyřeší jejich pořadí. Použijte verzi, očekávaný stav nebo sekvenční zpracování podle objektu. Starší událost nemá přepsat novější finální stav. Konflikt zviditelněte k ručnímu rozhodnutí, pokud jej nelze bezpečně vyřešit pravidlem.
Testujte souběh, vypršení a opravu
Spusťte stejný požadavek souběžně, přerušte spojení po odeslání a zopakujte ho během zpracování i po úspěchu. Ověřte stejný klíč s odlišným obsahem, neplatného klienta a opakování po uplynutí retenčního okna. Kontrolujte obchodní výsledek, sklad, doklad a události, nejen stavový kód.
Provoz potřebuje vidět operace uvízlé ve zpracování a bezpečně rozhodnout o pokračování. Ruční smazání idempotentního záznamu může vyvolat duplicitu, proto vytvořte řízený opravný postup. Sledujte míru opakování; náhlý nárůst může signalizovat timeout, chybu klienta nebo problém sítě.
- dva souběžné pokusy se stejným klíčem
- timeout po úspěšném uložení obchodního objektu
- stejný klíč s odlišným obsahem
- částečný úspěch navazující externí operace
- kontrolované opakování po ruční opravě
- vypršení uloženého klíče během obnovy služby
- bezpečný konflikt při neplatné identitě klienta
- jediný výsledný doklad ve všech systémech
Časté dotazy
Je idempotence totéž co deduplikace?
Souvisejí, ale nejsou totožné. Idempotence váže opakované technické pokusy na jeden záměr a výsledek. Deduplikace může později spojovat samostatné záznamy podle podobnosti nebo obchodních pravidel.
Kdo má vytvořit idempotentní klíč?
Obvykle klient, který zná hranici jednoho záměru a umí klíč opakovaně použít. Server určuje formát, rozsah, validaci a dobu uchování podle kontraktu API.
Jak dlouho uchovávat výsledek operace?
Podle nejdelšího realistického opakování, obchodního rizika a nákladů na uložení. Retenční pravidlo musí být zdokumentované; po jeho uplynutí může stejný klíč znamenat nový výsledek.
Zdroje a další čtení
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
