wip

Author: Julien00859

content/developer/reference/external_api.rst

@@ -343,15 +343,13 @@ Migrating from XML-RPC / JSON-RPC
 =================================
 
 Both the XML-RPC and JSON-RPC APIs at endpoints ``/xmlrpc``, ``/xmlrpc/2`` and ``/jsonrpc`` are
-scheduled for removal in Odoo 20 (fall 2026).
+scheduled for removal in Odoo 20 (fall 2026). Both RPC APIs expose the three same services: common,
+db (database) and object. All three services are deprecated.
 
-The RPC API defines 3 services:
-
-* common
-* db
-* object
+.. note::
 
-Every service has a replacement in Odoo 19.
+   The other controllers ``@route(type='jsonrpc')`` (known until Odoo 18 as ``type='json'``) are not
+   subject to this deprecation notice.
 
 
 Common service
@@ -380,7 +378,7 @@ The two ``login`` and ``authenticate`` functions return the user id correspondin
 a successful login. The user id and password are necessary for subsequent RPC calls to the *object*
 service. The JSON-2 API uses a different authentication scheme where neither the user id nor the
 password are used. It is still possible to get the user own id doing a JSON-2 request for
-``res.users/context_get`` with no ids.
+``res.users/context_get`` with no ids (the current user is extracted from the API key).
 
 Database service
 ----------------
@@ -402,8 +400,7 @@ The db service defines 13 fonctions:
 #. ``server_version()``
 
 Many of those function are accessible via the ``/web/database`` controllers. Those controllers
-work hand-in-hand with the HTML form at ``/web/database/manager`` and are accessible via HTTP as
-well.
+work hand-in-hand with the HTML form at ``/web/database/manager`` and are accessible via HTTP.
 
 The following controllers use verb ``POST`` and content-type ``application/x-www-form-urlencoded``.
 
@@ -436,4 +433,77 @@ Object service
 The object service defines 2 fonctions:
 
 #. ``execute(db, uid, passwd, model, method, *args)``
-#. ``execute_kw(db, uid, passwd, model, method, args, kw)``
+#. ``execute_kw(db, uid, passwd, model, method, args, kw={})``
+
+They both allow for access to all public model methods, including the generic ORM ones.
+
+Both functions are stateless. It means that the database, user id and user password are to be
+provided for each call. The model, method are arguments must likewas be provided. The ``execute``
+function takes as many extra positional arguments as necessary. The ``execute_kw`` function takes a
+``args`` list of positional arguments and an optional ``kw`` dict of keyword arguments.
+
+The records ids are extracted from the first ``args``. When the called method is decorated with
+``@api.model``, no record ids are extracted and ``args`` is left as-is. It is only possible to give
+a context with ``execute_kw`` as it is extracted from the keyword argument named ``context``.
+
+Example, to run the following:
+
+.. code:: python
+
+   (env['res.partner']
+       .with_user(2)  # admin
+       .with_context(lang='en_US')
+       .browse([1, 2, 3])
+       .read(['name'], load=None)
+   )
+
+Using XML-RPC (JSON-RPC would be similar):
+
+.. code:: python
+
+   from xmlrpc.client import ServerProxy
+   object = ServerProxy(...)
+   ids = [1, 2, 3]
+   fields = ['name']
+   load = None
+
+   object.execute("database", 2, "admin", "res.partner", "read", ids, fields, load)
+   object.execute("database", 2, "admin", "res.partner", "search", [
+       ids,
+       fields,
+   ], {
+       "context": {"lang": "en_US"},
+       "load": load,
+   })
+
+The JSON-2 API replaces the object service with a few differences. The database must only be 
+provided (via the ``X-Odoo-Database`` HTTP header) on systems where there are multiple databases
+available for a same domain. The login/password authentication scheme is replaced by an API key (via
+the ``Authorization: bearer`` HTTP header). The ``model`` and ``method`` are placed in the URL. The
+request body is a JSON object with all the methods arguments, plus ``ids`` and ``context``. All
+the arguments are named, there is no way in JSON-2 to call a function with positional arguments.
+
+Using JSON-2:
+
+.. code:: python
+
+   import requests
+
+   DATABSE = ...
+   DOMAIN = ...
+   API_KEY = "6578616d706c65206a736f6e20617069206b6579"
+
+   requests.post(
+       f"https://{DOMAIN}/json/2/res.partner/read",
+       headers={
+           # "X-Odoo-Database": DATABASE,  # only when DOMAIN isn't enough
+           "Authorization": f"bearer {API_KEY}",
+       },
+       json={
+           "ids": [1, 2, 3],
+           "context": {"lang": "en_US"},
+           "fields": ["name"],
+           "load": None,
+       },
+   ).json()
+

content/developer/reference/external_rpc_api.rst

@@ -9,6 +9,9 @@ External RPC API
    Both the XML-RPC and JSON-RPC APIs at endpoints ``/xmlrpc``, ``/xmlrpc/2`` and ``/jsonrpc`` are
    scheduled for removal in Odoo 20 (fall 2026). The :doc:`external_api` acts as a replacement.
 
+   The other controllers ``@route(type='jsonrpc')`` (known until Odoo 18 as ``type='json'``) are not
+   subject to this deprecation notice.
+
 Odoo is usually extended internally via modules, but many of its features and
 all of its data are also available from the outside for external analysis or
 integration with various tools. Part of the :ref:`reference/orm/model` API is