How to Design Your First Odoo API Endpoint: A Beginner’s Guide

Imagine you’re building a house. Before you can invite guests inside, you need a door—a way for them to enter and interact with your space. In the world of Odoo, an API endpoint is that door. It’s how external apps, services, or even other modules communicate with your Odoo system to fetch or update data.

If you’re new to Odoo development, designing your first API endpoint might seem intimidating. But don’t worry—this guide will walk you through the process step by step, using simple language and practical examples. By the end, you’ll be able to create a basic GET endpoint (the simplest type) and understand how to expand from there.

Why API Endpoints Matter in Odoo

Before diving into the "how," let’s clarify the "why." API endpoints allow:

• Integration – Connect Odoo with other tools (e.g., mobile apps, CRMs, payment gateways).
• Automation – Fetch or update data without manual input (e.g., syncing orders with an external inventory system).
• Customization – Extend Odoo’s functionality beyond its default features.

For example, if you want a mobile app to display a user’s latest invoices, you’d create an API endpoint that fetches that data from Odoo.

Prerequisites

To follow this guide, you’ll need:

1. A working Odoo environment (version 14 or later recommended).
2. Basic knowledge of Python (since Odoo is built on it).
3. Familiarity with Odoo module structure (models, views, controllers).

Step 1: Setting Up Your Module

If you don’t already have a custom module, create one:

1. Navigate to odoo/addons/ and create a new folder (e.g., my_custom_api).
2. Inside it, create two essential files:
   • __init__.py (can be empty).
   • __manifest__.py (metadata for your module).

Example __manifest__.py:

{
    'name': 'My Custom API',
    'version': '1.0',
    'summary': 'Adds custom API endpoints',
    'depends': ['base'],
    'data': [],
    'installable': True,
    'application': False,
}

Step 2: Creating a Controller

API endpoints in Odoo are typically defined in controllers (Python classes that handle HTTP requests).

1. Inside your module, create a folder named controllers.
2. Add an __init__.py file (can be empty).
3. Create a file named main.py with the following structure:

from odoo import http
from odoo.http import request

class MyAPIController(http.Controller):

    @http.route('/api/my_first_endpoint', type='json', auth='public')
    def my_first_endpoint(self, **kwargs):
        return {"message": "Hello, API World!"}

Breaking It Down:

• @http.route() – Defines the URL path (/api/my_first_endpoint).
• type='json' – Expects JSON input/output.
• auth='public' – Allows unauthenticated access (use 'user' for logged-in users).

Step 3: Testing Your Endpoint

Now, test your API using Postman or curl:

Using curl:

curl -X POST http://your-odoo-domain.com/api/my_first_endpoint -H "Content-Type: application/json" -d '{}'

Expected Response:

{"message": "Hello, API World!"}

🎉 Congratulations! You’ve built your first Odoo API endpoint.

Step 4: Fetching Real Data (GET Request)

Let’s make the endpoint more useful by fetching data from an Odoo model (e.g., res.partner for contacts).

Update main.py:

@http.route('/api/get_partners', type='json', auth='user')
def get_partners(self, **kwargs):
    partners = request.env['res.partner'].search([])
    return {
        "partners": [
            {"id": p.id, "name": p.name, "email": p.email}
            for p in partners
        ]
    }

Key Improvements:

• auth='user' – Ensures only authenticated users can access.
• request.env['res.partner'] – Queries the res.partner model.
• Returns a list of partners with selected fields (ID, name, email).

Testing:

curl -X POST http://your-odoo-domain.com/api/get_partners -H "Content-Type: application/json" -d '{}'

Pro Tips for Better API Design

1. Keep It Simple – Start with basic GET requests before handling POST/PUT.
2. Validate Inputs – Check if required parameters are provided.
3. Handle Errors Gracefully – Return helpful error messages (e.g., {"error": "Missing required field"}).
4. Secure Your Endpoints – Use auth='user' for sensitive data.

Next Steps

Now that you’ve built a GET endpoint, try:

• Creating a POST endpoint to add new records.
• Adding query parameters (e.g., /api/get_partners?limit=10).
• Exploring Odoo’s RPC API for advanced use cases.

Final Thoughts

Designing your first Odoo API endpoint is like opening a door—once you’ve built it, endless possibilities for integration and automation await. Start small, test often, and soon you’ll be building robust APIs like a pro.

Got questions? Drop them in the comments below, or bookmark this guide for future reference! 🚀