/xmlrpc and /jsonrpc are getting deprecated in Odoo 19.0

[Julien00859]

Hello friends at the OCA 👋

We (Odoo SA) plan on deprecating both the /xmlrpc and /jsonrpc endpoints in 19.0 for removal in saas-19.1 (20.0). The /json/2 endpoint (landed in 18.4) should act as replacement.

The new endpoint works as follow:

POST /json/2/<model>/<method> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <api-key>
X-Odoo-Database: <dbname>

{
    "ids": [],
    "context": {},
    "kwarg1": value1,
    "kwarg2": value2,
    ...
}

HTTP/1.1 <sensible status code> <sensible phrase>
Content-Type: application/json

<json>

Mandatory:

• (url) model
• (url) method
• (header) Authorization, using a API key that must be generated via the user's profile.

Optional:

• (header) X-Odoo-Database, is determined from the hostname, or odoo-bin -d, when missing.
• (request) ids, is an empty list by default
• (request) context: is an empty dict by default

The response typically will be 200 OK with a Content-Type: application/json and the result of method immediately serialized as JSON. There's no longer any wrapping, {"result": {...}} and {"error": {...}} are gone.

In case of error, the response typically will be a 4xx/5xx status code, with a Content-Type: application/json, and the error message as a json-string in the body, example:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

"missing a required argument: 'domain'"

Note that there are some errors that can occur too early in our http stack and that we cannot serialize as json. For those the http status is sensitive too (a 4xx/5xx error) but the Content-Type is text/html.

---

We are reaching for you because we believe that most users are using this repository to communicate with Odoo. We believe you guys are very knowledgeable about the external API and the challenges using it involves. We would like to use this issue as a forum, to work together and make it the least painful to the users.

On our side we plan on updating the documentation, and communicate heavily during the OXP. I would very much like be able to say "if you are using the OdooRPC module from the OCA, you are covered.".

The endpoint has been merged in saas-18.4, and is considered stable-ish. The time window before 19.0 is closing rapidly but we still are in a position to change the controller (a bit) to accommodate for a better transition.

But one thing is pretty sure: we want to rely more on api-keys, and less on user/password pairs. We think it is gonna be the main pain-point for users, we assume it.

Sorry for the short notice, we agreed on the deprecation schedule with Fabien and Antony last Wednesday, one week ago. Their original plan was to entirely remove /xmlrpc and /jsonrpc in 19.0, we negotiated the endpoints to be deprecated in 19.0, and only removed in saas-19.1 (upcoming 20.0).

For the Odoo Framework teams
Julien (juc)

cc @rco-odoo @kmagusiak (krma) @PiaCOS (elco) @BastienFafchamps (bafa)

[Julien00859]

Update, the error is now a json-serialized object with the following entries:

  {
    "name": "werkzeug.exceptions.Unauthorized",
    "message": "Invalid apikey",
    "arguments": ["Invalid apikey", 401],
    "context": {},
    "debug":
  }

traceback in debug

see odoo/odoo#223070

[thomaspaulb]

Hello friends at Odoo!

While this "odoorpc" library is used a lot, it is by no means the only one of its sort - there are lots more libs for nodejs, PHP etc. All of these would have to be made compatible with the new API, while still remaining compatible with the old API as well, for earlier versions.

With a lot of things changing between Odoo versions, the one constant that people could count on was the API remaining stable. To save on maintenance cost, customers have swapped custom code for external integrations via API. So this change will make those people quite unhappy.

I've raised this point before with @fpodoo but his response was, Odoo can't evolve without a cadence of breaking changes every 1 year. While that may be true, it drives up cost of ownership for anyone with customizations and makes some customers decide to move away from Odoo.

[pedrobaeza]

Hi @Julien00859 thanks for warning us. @sebalix is the usual maintainer of the library, although not sure if he's able to work on this. Let's see if he can say something.

@thomaspaulb your comment is off-topic, so let's focus this thread in the proper thing. The change is done already, so no argue about "not changing it". That discussion should go in other place, as well as the strategy followed in your implementations (I see such strategy of doing APIs worst for example).

[Julien00859]

We have a bit of internal feedback too. We had to upgrade our own tools and the pain points were as follow:

No positional arguments

There's no way to provide a list of args, only named arguments kwargs. There has been a heated debate at work and we ultimately decided to go on with keyword-only. The main rational is "it looks better". In our internal tools, we added a small translation layer for the ORM methods, so that search([("name", "=", "bob")] is understood as domain=[("name", "=", "bob")]. For the other models we download the json document at /doc/<model>.json (session) or /doc-bearer/<model>.json (API key) to look up the function signature and translate the args to kwargs.

API key rotation

At the moment only admins can create permanent API keys. Other users can create keys that last for maximum 3 months. This is in line with the OWASP recommandations to rotate secrets on a regular basis. At the moment, the only practical way to renew/extend API keys is to use the web client. There are no API to ease the rotation/renewal/extension of API keys at the moment, we are still no sure of the direction to take, if such an API is desirable, and if so what it should looks like.

[Julien00859]

While this "odoorpc" library is used a lot, it is by no means the only one of its sort - there are lots more libs for nodejs, PHP etc. All of these would have to be made compatible with the new API

You, the community, are actually much more knowledgeable about what exists / what is used / who to reach. I would be very grateful if you could spread the word to other library maintainers. In all cases the RPC API will still work during the 19.0 lifetime and we have several talks on this subject scheduled for the OXP.

[kmagusiak]

Note that with the new API, odoo rpc libraries become less useful. They may offer features on top of the basic API for exploration.

If all you want to do is a call, you can use any library without a lot of boilerplate and use the /doc endpoint to explore what's there.

import httpx
API_KEY = ...
cli = httpx.Client(base_url=..., headers={'Authorization': f'Bearer {API_KEY}'})
resp = cli.post('/json/2/sale.order/search_read', json={'domain': [], 'limit': 5})
resp.raise_for_status().json()

[MaartenUreel]

Note that with the new API, odoo rpc libraries become less useful. They may offer features on top of the basic API for exploration.

If all you want to do is a call, you can use any library without a lot of boilerplate and use the /doc endpoint to explore what's there.

import httpx
API_KEY = ...
cli = httpx.Client(base_url=..., headers={'Authorization': f'Bearer {API_KEY}'})
resp = cli.post('/json/2/sale.order/search_read', json={'domain': [], 'limit': 5})
resp.raise_for_status().json()

Are there any docs available on this new endpoint already except for this Github thread? Because I cannot get it to work 😬

e.g. response = self.client.post("/json/2/sale.order/search", json={"domain": [], "limit": 1})

"OdooWebJson2Controller.web_json_2_rpc() missing 2 required positional arguments: 'ids' and 'context'"

[kmagusiak]

@Julien00859 could you link the documentation link? (whn the doc PR will be merged)

[Julien00859]

The documentation is incoming at odoo/documentation#14091

Hello @MaartenUreel, I just tested it, with both the latest saas-18.4 and master. It works fine with both requests and httpx.

>>> import requests
>>> apikey='a2184cfd3b4322d9f83c474de8fb3590fd319009'
>>> headers={'Authorization': f'bearer {apikey}'}
>>> requests.post('http://odoo.localhost/json/2/sale.order/search', headers=headers, json={'domain': [], 'limit': 1})
<Response [200]>
>>> res = _
>>> res.json()
[16]

Would you mind sending me the complete http request? Along with the complete server logs?

"OdooWebJson2Controller.web_json_2_rpc() missing 2 required positional arguments: 'ids' and 'context'"

This error is odd, the two ids and context arguments have a default value (empty tuple and empty frozendict). I don't see how you could get this error.

Can you please make sure you are using the latest saas-18.4 or master?

[MaartenUreel]

The documentation is incoming at odoo/documentation#14091

Hello @MaartenUreel, I just tested it, with both the latest saas-18.4 and master. It works fine with both requests and httpx.

import requests
apikey='a2184cfd3b4322d9f83c474de8fb3590fd319009'
headers={'Authorization': f'bearer {apikey}'}
requests.post('http://odoo.localhost/json/2/sale.order/search', headers=headers, json={'domain': [], 'limit': 1})
<Response [200]>
res = _
res.json()
[16]
Would you mind sending me the complete http request? Along with the complete server logs?

"OdooWebJson2Controller.web_json_2_rpc() missing 2 required positional arguments: 'ids' and 'context'"

This error is odd, the two ids and context arguments have a default value (empty tuple and empty frozendict). I don't see how you could get this error.

Can you please make sure you are using the latest saas-18.4 or master?

I tested it on Odoo Online, Odoo saas~18.4+e.

But perhaps we should not hijack the thread here; I will pick it up later and if I run into it I can probably best open a support ticket?

[Julien00859]

But perhaps we should not hijack the thread here; I will pick it up later and if I run into it I can probably best open a support ticket?

@MaartenUreel please do

[florentx]

Documentation:

• https://github.com/odoo/documentation/blob/master-19.0-json2doc-juc-462161-fw/content/developer/reference/external_api.rst

[Julien00859]

https://www.odoo.com/documentation/19.0/developer/reference/external_api.html

[yajo]

I remember that in OXP somebody said the old API would be removed in v20. Is there any chance that it stays for at least v21? Even if it is behind some setting?

I've had many conversations with Odoo partners at OXP, OCA events, etc. Many have the norm of migrating every 2 years, as a practical way to deal with the fast evolution of the ecosystem.

I think that giving us only 1 version to deprecate such a critical thing as the API is too low. 2 versions would make a big difference.