Key Takeaways
- Odoo exposes XML-RPC and JSON-RPC APIs for full CRUD access to every model and method in the system
- Use API keys instead of passwords for production integrations to improve security and avoid credential rotation issues
- search_read combines search and read in a single call, reducing round trips and improving integration performance
- Odoo domain syntax (field, operator, value tuples) powers all filtering and must be mastered for efficient queries
- REST API is available in Enterprise edition natively, or via third-party modules for Community edition
API Protocols Comparison
Odoo supports three API protocols. XML-RPC is the oldest and most documented, JSON-RPC is the internal protocol used by the web client, and REST API is the modern option available in Enterprise.
| Protocol | Format | Auth | Edition | Use Case |
|---|---|---|---|---|
| XML-RPC | XML | Password/API key | All | Legacy integrations, wide library support |
| JSON-RPC | JSON | Session cookie | All | Web apps, internal API calls |
| REST API | JSON | Bearer token | Enterprise | Modern integrations, mobile apps |
For new integrations, use JSON-RPC for Community edition or REST API for Enterprise. XML-RPC works but is verbose and slower due to XML serialization overhead.
Authentication and Security
Every API call requires authentication. The method varies by protocol but always involves identifying the database, user, and credential. API keys are strongly recommended over passwords.
- Generate an API key: Settings > Users > select user > API Keys tab > New API Key
- Store keys securely in environment variables, never in source code
- Use the authenticate endpoint to obtain a user ID (uid) for subsequent calls
- For JSON-RPC, maintain session cookies across requests
- Implement token refresh and reconnection logic for long-running integrations
Restrict API access to known IP addresses using Odoo's proxy or firewall rules. Open API endpoints are a common attack vector for brute-force authentication attempts.
CRUD Operations and Domain Filters
All data manipulation follows the same pattern: specify the model name, method, and arguments. The four core methods are search_read, create, write, and unlink.
| Method | Purpose | Key Arguments |
|---|---|---|
| search_read | Query records | domain, fields, limit, offset, order |
| create | Insert new record | field values dict |
| write | Update records | record IDs, field values dict |
| unlink | Delete records | record IDs |
Domain filter examples: [('state', '=', 'sale')] finds confirmed sales orders. [('amount_total', '>', 1000), ('partner_id.country_id.code', '=', 'US')] finds large US orders. Combine with '|' operator for OR logic.
Handling Relational Fields
Many-to-one, one-to-many, and many-to-many fields use special command syntax for write operations. This syntax is the most common source of confusion for developers new to the Odoo API.
| Command | Syntax | Effect |
|---|---|---|
| Link | (4, id, 0) | Add existing record to relation |
| Unlink | (3, id, 0) | Remove from relation without deleting |
| Delete | (2, id, 0) | Remove from relation and delete record |
| Create | (0, 0, values) | Create new record and link |
| Replace | (6, 0, [ids]) | Replace all linked records with new set |
To add a line to a sales order: write(order_id, {'order_line': [(0, 0, {'product_id': 1, 'product_uom_qty': 5})]}) creates a new line and links it automatically.
Performance Optimization
API performance depends on network latency, query complexity, and result set size. Batch operations and selective field loading have the largest impact on throughput.
- Request only needed fields to reduce payload size and database load
- Use limit and offset for pagination instead of fetching all records
- Batch create/write operations: pass lists of values instead of looping individual calls
- Cache the authenticated uid to avoid re-authenticating on every request
- Use search_count before search_read to show totals without loading full records
- Enable server-side caching for read-heavy integrations with infrequently changing data
Frequently Asked Questions
Related services from Verbsz Technologies
If this article is relevant to a project on your roadmap, these are the services our team typically delivers.