Odxproxy Clients

ODXProxy Clients

Help the user build applications against an Odoo ERP through ODXProxy, and understand the target Odoo instance's data structure first so the code matches reality.

Mental model (read this first)

ODXProxy is a Rust reverse proxy exposing one JSON-RPC 2.0 API in front of any number of Odoo instances. Apps call the proxy; the proxy calls Odoo's execute_kw. Two facts drive almost every mistake:

1. Two separate keys. The proxy key goes in the x-api-key HTTP header (client → proxy). The Odoo user key goes in the request body as odoo_instance.api_key (proxy → Odoo). They are never the same value.
2. HTTP 200 can still be an error. Odoo logic/permission failures come back inside a populated error object on a 200 response. Always inspect error before reading result.

Endpoint: POST /api/odoo/execute. Only 9 actions are allowed through: search_count, search, read, fields_get, search_read, create, write, unlink, call_method (arbitrary method — needs fn_name).

Minimal request body:

{
  "id": "req-1",
  "action": "search_read",
  "model_id": "res.partner",
  "params": [[["is_company", "=", true]]],
  "keyword": { "fields": ["id", "name", "email"], "limit": 20 },
  "odoo_instance": { "url": "https://erp.example.com", "db": "prod", "user_id": 2, "api_key": "<odoo user key>" }
}

params = positional args to execute_kw; keyword = kwargs (fields, limit, offset, order, context, ...). Full field/type details, all actions, and the error catalog live in references/ — load them as needed rather than guessing.

Workflow

1. Discover the target Odoo model with fields_get — before serializing into the native language. Do not assume field names; Odoo models are heavily customized per instance. Always call fields_get on the model first to get its real schema (field names, type, required, relation, selection), then map that schema into your target language's native types (structs/classes/DTOs/models). Writing the native data model before introspecting is the most common source of bugs.

• Every official SDK exposes fields_get first-class — as a method in most, as OdxAction.FieldsGet in .NET. Use it when working inside a chosen SDK; call_method is not needed for this, fields_get is one of the 9 actions.
• No SDK yet (or just exploring)? scripts/odx.py is a zero-dependency CLI over /api/odoo/execute for running fields_get and search_read against the live instance.
• Then sample a few real records with search_read to confirm value shapes (e.g. many2one as [id, "name"], which selection values actually occur).
• Full recipe — classify fields, follow relations, map the model graph: references/odoo-introspection.md.

If you have no live instance, say so and design against documented Odoo core models, flagging every field the user must confirm.

2. Pick the client path. Either an official SDK or a hand-rolled client:

• Official SDKs share one intent: hold proxy URL + x-api-key once, bind an Odoo instance, call one method per action, catch typed exceptions — but the actual APIs have drifted per language, so read the real source before writing code. Notable exceptions: the com.terrakernel Kotlin client is low-level (build the request yourself), and the .NET client has no per-action methods at all — one ExecuteAsync plus an OdxAction enum, with params/keyword passed as raw JSON bytes. Language specifics: references/sdks.md.
• Custom client: implement the envelope and the 200-with-error check yourself. Contract is in references/api-reference.md.

3. Build, mapping each user operation to one allowed action. If an operation needs an Odoo method outside the 8 CRUD actions (e.g. action_confirm), use call_method with fn_name. Details + per-action param shapes: references/actions.md.

4. Handle errors by code, not by HTTP status alone. Map the JSON-RPC error codes to user-facing behavior (retry on timeout, surface Odoo validation messages, fail fast on auth/license). Catalog: references/errors.md.

Reference index

Local reference repos

The official SDK sources live on GitHub under https://github.com/terrakernel (per-language repo URLs are in references/sdks.md). Published SDKs: Python, Java (Kotlin), PHP, Kotlin, Swift, JavaScript/TS, and .NET/C# (NuGet TerraKernel.OdxClient). Dart exists but is not published yet — don't recommend it. Before relying on exact symbol names, read the real source of the SDK the user is on — browse/clone its repo, or read a local checkout if you have one — because this skill's summaries can drift from the code.