REST API integrace znějí jednoduše — pošlete HTTP požadavek, dostanete JSON odpověď. V realitě ale spolehlivá integrace, která funguje rok i pět let bez zásahu, vyžaduje víc přemýšlení. Podíváme se na praktické tipy z reálných projektů, kde jsme napojovali Odoo ERP a Oracle databázi do PHP webu.

Synchronní vs asynchronní integrace

První rozhodnutí je, jestli má uživatel na výsledek integrace čekat, nebo ne. Synchronní (čeká) je jednodušší, ale když externí systém vypadne, padá i váš web. Asynchronní (přes frontu) je robustnější, ale komplexnější.

Naše pravidlo: akci, která trvá víc než 1 sekundu nebo závisí na cizím systému, řešíme asynchronně. Uživatel nečeká, požadavek běží na pozadí přes frontu, uživatel vidí stav přes opakované dotazování nebo notifikaci.

Odoo přes XML-RPC vs REST

Odoo má dvě API rozhraní. XML-RPC je nativní, plně dokumentované a má přístup ke všem modelům. REST je standardní, ale potřebuje doplňkový modul (často web_api nebo vlastní modul).

Pro nové integrace doporučujeme REST + JSON — jednodušší ladění, lepší nástroje. Pro starší integrace nebo přístup k méně obvyklým modelům je XML-RPC praktičtější. V PHP používáme Ripcord nebo nativní xmlrpc_* funkce.

Oracle z PHP přes OCI8 driver

Připojení PHP k Oracle databázi řeší rozšíření OCI8. Instalace není triviální — potřebujete Oracle Instant Client a správně nakonfigurovaný PHP modul. Ale po nasazení je výkon výborný a podpora parametrizovaných proměnných předchází SQL injection.

V projektech typicky obalujeme OCI8 do tenké PHP třídy s metodami query(), execute(), fetchAll() — tím izolujeme Oracle specifika od zbytku aplikace. Kdybychom někdy migrovali na PostgreSQL, změníme jen jednu třídu.

Retry logika a idempotence

Síť je nespolehlivá. Externí systém může vypršet, vrátit 502, nebo prostě neodpovědět. Bez retry logiky je každá taková situace přerušený import nebo neodeslaný objednávkový e-mail.

Naše běžná implementace:

  • Exponential backoff — 1 s, 2 s, 4 s, 8 s, max 60 s mezi pokusy
  • Maximálně 5 pokusů — po nich označit jako selhané a poslat upozornění
  • Idempotency key — UUID v hlavičce, aby externí systém věděl, že jde o opakovaný pokus, ne novou operaci
  • Opakovaný pokus jen při 5xx nebo síťových chybách — 4xx chyby jsou platné odpovědi, opakování nepomůže

Rate limiting a backoff

Externí API mají rate limity (Odoo cloud má například 100 req/min). Při větším objemu potřebujete vlastní omezovač rychlosti, který čeká, dokud se neuvolní API kvóta. V PHP používáme Redis jako počítadlo — atomické INCR s expirací na 60 sekund.

Když narazíte na 429 Too Many Requests, externí systém typicky pošle i Retry-After hlavičku. Respektujte ji — nemá smysl okamžitě zkoušet znovu.

Logy a monitoring

Bez logů je integrace černá skříňka. Logujeme každý odchozí požadavek se statusem odpovědi, časem a obsahem požadavku i odpovědi. Citlivá data (tokeny, hesla) maskujeme. V produkci rotujeme logy denně a držíme 30 dní.

Kritické integrace mají kontrolní signál — každou hodinu běží malá synchronizace, a když se nepodaří, posíláme upozornění. To je výrazně lepší, než když klient v pondělí ráno zjistí, že se přes víkend nesynchronizovaly objednávky.

Tipy z reálných projektů

  • Vždy verzovat API — pokud vyvíjíte vlastní API, dejte mu verzi v URL (/api/v1/) od začátku
  • Příjemci webhooků musí být idempotentní — externí systém vás může notifikovat dvakrát
  • Testujte s offline simulací — atrapa externího API pro lokální vývoj a CI
  • Dokumentujte i chování při opakovaných pokusech — když bude klient ladit, potřebuje vědět, co systém dělá při selhání

Závěr

Spolehlivá integrace není jednorázový projekt — je to disciplína, která se odráží v každém řádku kódu. Investice do retry logiky, idempotence a monitoringu se vrátí mnohonásobně v menších produkčních problémech. Pokud chystáte integraci s Odoo, Oracle nebo jiným systémem, ozvěte se nám.