REST API integrácie znejú jednoducho — pošlete HTTP požiadavku, dostanete JSON odpoveď. V realite však spoľahlivá integrácia, ktorá funguje rok aj päť rokov bez zásahu, vyžaduje viac premyslenia. Pozrieme sa na praktické tipy z reálnych projektov, kde sme napájali Odoo ERP a Oracle databázu do PHP webu.

Synchrónne vs asynchrónne integrácie

Prvé rozhodnutie je, či má užívateľ na výsledok integrácie čakať alebo nie. Synchrónne (čaká) je jednoduchšie, ale ak externý systém vypadne, padá aj váš web. Asynchrónne (cez frontu) je robustnejšie, ale komplexnejšie.

Naše pravidlo: akciu, ktorá trvá viac ako 1 sekundu alebo závisí od cudzieho systému, riešime asynchrónne. Používateľ nečaká, požiadavka beží na pozadí cez frontu, používateľ vidí stav cez opakované dopytovanie alebo notifikáciu.

Odoo cez XML-RPC vs REST

Odoo má dve API rozhrania. XML-RPC je natívny, plne dokumentovaný a má prístup ku všetkým modelom. REST je štandardný, ale potrebuje doplnkový modul (často web_api alebo vlastný modul).

Pre nové integrácie odporúčame REST + JSON — jednoduchšie ladenie, lepšie nástroje. Pre staršie integrácie alebo prístup k zriedkavým modelom je XML-RPC praktickejšie. V PHP používame Ripcord alebo natívne xmlrpc_* funkcie.

Oracle z PHP cez OCI8 driver

Pripojenie PHP k Oracle databáze rieši rozšírenie OCI8. Inštalácia nie je triviálna — potrebujete Oracle Instant Client a správne nakonfigurovaný PHP modul. Ale po nasadení je výkon výborný a podpora parametrizovaných premenných predchádza SQL injection.

V projektoch typicky obaľujeme OCI8 do tenkej PHP triedy s metódami query(), execute(), fetchAll() — tým izolujeme Oracle špecifiká od zvyšku aplikácie. Keby sme niekedy migrovali na PostgreSQL, zmeníme len jednu triedu.

Retry logika a idempotency

Sieť je nespoľahlivá. Externý systém môže vypršať, vrátiť 502, alebo proste neodpovedať. Bez retry logiky je každá takáto situácia prerušený import alebo neodoslaný objednávkový email.

Naša bežná implementácia:

  • Exponential backoff — 1s, 2s, 4s, 8s, max 60s medzi pokusmi
  • Maximum 5 pokusov — po nich označiť ako zlyhané a poslať upozornenie
  • Idempotency key — UUID v hlavičke, aby externý systém vedel, že je to opakovaný pokus, nie nová operácia
  • Opakovaný pokus iba pri 5xx alebo sieťových chybách — 4xx chyby sú platné odpovede, opakovanie nepomôže

Rate limiting a backoff

Externé API majú rate limity (Odoo cloud má napríklad 100 req/min). Pri väčšom objeme potrebujete vlastný obmedzovač rýchlosti, ktorý čaká, kým neuvoľníte API kvótu. V PHP používame Redis ako počítadlo — atomické INCR s expiráciou na 60 sekúnd.

Keď narazíte na 429 Too Many Requests, externý systém typicky pošle aj Retry-After hlavičku. Rešpektujte ho — nemá zmysel okamžite skúšať znova.

Logy a monitoring

Bez logov je integrácia čierna skrinka. Logujeme každú odchádzajúcu požiadavku so statusom odpovede, časom a obsahom požiadavky aj odpovede. Citlivé dáta (tokeny, heslá) maskujeme. V produkcii rotujeme logy denne a držíme 30 dní.

Kritické integrácie majú kontrolný signál — každú hodinu beží malá synchronizácia, a keď sa nepodarí, posielame upozornenie. To je výrazne lepšie, ako keď klient o pondelok ráno nájde, že cez víkend sa nesynchronizovali objednávky.

Tipy z reálnych projektov

  • Vždy verziovať API — ak vyvíjate vlastné API, dajte mu verziu v URL (/api/v1/) od začiatku
  • Príjemcovia webhookov musia byť idempotentní — externý systém vás môže notifikovať dvakrát
  • Testujte s offline simuláciou — atrapa externého API pre lokálny vývoj a CI
  • Dokumentujte aj správanie pri opakovaných pokusoch — keď klient bude ladiť, potrebuje vedieť, čo systém robí pri zlyhaní

Záver

Spoľahlivá integrácia nie je jednorazový projekt — je to disciplína, ktorá sa odráža v každom riadku kódu. Investícia do retry logiky, idempotency a monitoringu sa vráti mnohonásobne v menších produkčných problémoch. Ak chystáte integráciu s Odoo, Oracle alebo iným systémom, ozvite sa nám.