REST APIs and External Integrations

Introduction#

Every integration ticket sounds unique; the engineering patterns repeat. Authentication, mapping, conflict resolution, and observability matter more than whether you call it REST or RPC.

This article compares Odoo-native integration surfaces with external Python services and gives implementation guardrails for Odoo 16/17 deployments.

JSON-RPC and XML-RPC basics#

Authenticate to /web/session/authenticate or use API keys where supported, then call execute_kw on models: create, read, write, search_read, unlink. Batch with search_read domains and explicit field lists to reduce payload.

Use dedicated integration users — not admin — with groups matching least privilege. Rotate passwords and store secrets in ir.config_parameter or environment variables, not Git.

• ▸context in execute_kw passes lang, company, active_test
• ▸name_search and custom @api.model methods expose safe operations
• ▸Avoid unlink in sync jobs — archive or cancel per business rules

Custom HTTP controllers#

controllers/main.py defines routes with type='json' or type='http', auth='user'|'public'|'none', methods, csrf=False only when justified for external POST webhooks with alternate auth.

Validate signatures (Shopify HMAC, Stripe webhook secret) before touching env. Return proper HTTP status codes — partners retry 5xx, not vague 200 with error body.

Mapping, idempotency, and conflict handling#

Store partner ids on models (shopify_product_id) or a sync.mapping model with (source, external_id) unique constraint. Upsert: search mapping → write or create with same external key.

Last-write-wins is dangerous for inventory and invoices. Define authority per field — Odoo wins on posted accounting; channel wins on listing title if merchandising lives in Shopify.

External Python and message buses#

When throughput, scheduling, or secret isolation exceeds Odoo worker comfort, run a Python service with official odoorpc, xmlrpc.client, or REST to Odoo. Use message queues for burst traffic.

Business decision whether integration is in scope for Odoo module vs external service overlaps the Customization pillar — link there for buy/build; here focus on engineering split.

Observability and staging#

Log correlation ids across middleware and Odoo chatter or custom log model. Replay failed payloads from dead-letter storage — not by re-firing production webhooks blindly.

Staging must mirror ACL of integration user and include sandbox credentials. Never point dev middleware at production Odoo without read-only safeguards.

Practical recommendations#

• ✓Define integration contract document: models, fields, direction, frequency, error codes.
• ✓Wrap outbound HTTP in timeout + retry with exponential backoff; respect 429 headers.
• ✓Use savepoints or queue rows for partial failure — one bad SKU must not abort entire catalog.
• ✓Expose health endpoint or heartbeat record support can monitor.
• ✓Version controller URLs (/api/v1/) when external clients depend on shape.
• ✓Pen-test public routes — auth='public' routes are internet-facing attack surface.

Common mistakes#

• !Admin API user in production scripts on laptops.
• !sudo() in webhook handler without partner verification.
• !Creating duplicate products every sync — no external id search.
• !Synchronous 30s partner call inside HTTP request worker.
• !Writing posted invoice fields from ecommerce webhook.
• !csrf=False on routes that accept browser cookies without token checks.

Conclusion#

Integrations succeed on mapping, least-privilege users, and idempotent jobs — not on picking RPC vs REST labels.

Split middleware from Odoo when rate limits and retries dominate; keep financial and stock truth inside Odoo transactions.