Skip to content

Commit f9cead3

Browse files
Julien00859Julien00859
committed
wip
1 parent 46a9f49 commit f9cead3

File tree

2 files changed

+118
-57
lines changed

2 files changed

+118
-57
lines changed

‎content/developer/reference/external_api.rst

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,22 @@
1-
============
2-
External API
3-
============
1+
================
2+
External RPC API
3+
================
4+
5+
.. deprecated:: 19.0
46

57
Odoo is usually extended internally via modules, but many of its features and
68
all of its data are also available from the outside for external analysis or
79
integration with various tools. Part of the :ref:`reference/orm/model` API is
810
easily available over XML-RPC_ and accessible from a variety of languages.
911

10-
.. important::
11-
Starting with PHP8, the XML-RPC extension may not be available by default.
12-
Check out the `manual <https://www.php.net/manual/en/xmlrpc.installation.php>`_
13-
for the installation steps.
12+
Starting with PHP8, the XML-RPC extension may not be available by default.
13+
Check out the `manual <https://www.php.net/manual/en/xmlrpc.installation.php>`_
14+
for the installation steps.
1415

15-
.. note::
16-
Access to data via the external API is only available on *Custom* Odoo pricing plans. Access to
17-
the external API is not available on *One App Free* or *Standard* plans. For more information
18-
visit the `Odoo pricing page <https://www.odoo.com/pricing-plan>`_ or reach out to your Customer
19-
Success Manager.
16+
Access to data via the external API is only available on *Custom* Odoo pricing plans. Access to
17+
the external API is not available on *One App Free* or *Standard* plans. For more information
18+
visit the `Odoo pricing page <https://www.odoo.com/pricing-plan>`_ or reach out to your Customer
19+
Success Manager.
2020

2121
.. seealso::
2222
- :doc:`Tutorial on web services <../howtos/web_services>`

‎content/developer/reference/external_json2_api.rst

Lines changed: 106 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -16,32 +16,96 @@ Request
1616

1717
POST a json object at the ``/json/2/<model>/<method>`` URL.
1818

19-
.. code:: http
20-
21-
POST /json/2/res.partner/search_read HTTP/1.1
22-
Host: mycompany.odoo.com
23-
X-Odoo-Database: mycompany
24-
Authorization: Bearer 6578616d706c65206a736f6e20617069206b6579
25-
Content-Type: application/json; charset=utf-8
26-
User-Agent: mysoftware python-requests/2.25.1
2719

28-
{
29-
"ids": [],
30-
"context": {
31-
"lang": "en_US"
20+
.. tabs::
21+
22+
.. code-tab:: http
23+
24+
POST /json/2/res.partner/search_read HTTP/1.1
25+
Host: mycompany.odoo.com
26+
X-Odoo-Database: mycompany
27+
Authorization: Bearer 6578616d706c65206a736f6e20617069206b6579
28+
Content-Type: application/json; charset=utf-8
29+
User-Agent: mysoftware python-requests/2.25.1
30+
31+
{
32+
"ids": [],
33+
"context": {
34+
"lang": "en_US"
35+
}
36+
"domain": [
37+
["name", "ilike", "%deco%"],
38+
["is_company", "=", true]
39+
],
40+
"fields": ["name"],
3241
}
33-
"domain": [
34-
["name", "ilike", "%deco%"],
35-
["is_company", "=", true]
36-
],
37-
"fields": ["name"],
38-
}
42+
43+
.. code-tab:: python
44+
45+
import requests
46+
47+
HOST = "https://mycompany.odoo.com"
48+
DATABASE = "mycompany"
49+
API_KEY = ... # get it from a secure location
50+
51+
response = requests.post(
52+
HOST + "/json/2/res.partner/search_read",
53+
headers={
54+
"Authorization": f"Bearer {API_KEY}",
55+
"X-Odoo-Database": DATABASE,
56+
},
57+
json={
58+
"ids": [],
59+
"context": {
60+
"lang": "en_US",
61+
}
62+
"domain": [
63+
("name", "ilike", "%deco%"),
64+
("is_company", "=", True),
65+
],
66+
"fields": ["name"],
67+
},
68+
)
69+
response.raise_for_status()
70+
data = response.json()
71+
72+
.. code-tab:: javascript
73+
74+
(async () => {
75+
const HOST = "https://mycompany.odoo.com";
76+
const DATABASE = "mycompany";
77+
const API_KEY = ; // get it from a secure location
78+
79+
const request = {
80+
method: "POST",
81+
headers: {
82+
"Content-Type": "application/json",
83+
"Authorization": "Bearer " + API_KEY,
84+
"X-Odoo-Database": DATABASE,
85+
},
86+
body: {
87+
domain: [
88+
["name", "ilike", "%deco%"],
89+
["is_company", "=", true],
90+
],
91+
fields: ["name"],
92+
},
93+
};
94+
95+
const response = await fetch(HOST + "/json/2/res.partner/search_read", request);
96+
if (response.ok) {
97+
const data = await response.json();
98+
console.log(data)
99+
} else {
100+
// Handle errors
101+
}
102+
})();
39103

40104
The body must be a json-object containing the arguments for the model's method. Both ``ids`` and
41105
``context`` are special arguments: they are used to craft the environment and recordset on which the
42106
method is executed.
43107

44-
The headers ``Host``, ``Authorization`` (bearer + api key) and ``Content-Type`` are required. The
108+
The headers ``Host``, ``Authorization`` with an API key and ``Content-Type`` are required. The
45109
``X-Odoo-Database`` header is only necessary when multiple databases are hosted behind a same
46110
``Host``. A ``User-Agent`` with the name of the software where the request comes from is
47111
recommended.
@@ -67,7 +131,6 @@ A **200 OK** status with the method's return value serialized as json in the bod
67131
{"id": 25, "name": "Deco Addict"}
68132
]
69133
70-
71134
Error
72135
-----
73136

@@ -84,19 +147,6 @@ A **4xx**/**5xx** status with the error message serialized as a json string in t
84147
The complete traceback is available in the server log, at the same date as the error response.
85148

86149

87-
88-
Database
89-
========
90-
91-
Depending on the deploiement, the ``Host`` and/or ``X-Odoo-Database`` request headers might be
92-
required. The ``Host`` header is required on servers where Odoo is installed next to other web
93-
applications, so a web-server/reverse-proxy is able to route the request to the Odoo server. The
94-
``X-Odoo-Database`` header is required when a single Odoo server hosts multiple databases, and that
95-
:ref:`dbfilter` wasn't configured to use the ``Host`` header.
96-
97-
Most HTTP client libraries automatically set the ``Host`` header using the connection url.
98-
99-
100150
API Key
101151
=======
102152

@@ -119,13 +169,14 @@ Create a new API key for a user via :guilabel:`Preferences`, :guilabel:`Account
119169

120170
A description and a duration are needed to create a new api key. The description makes it possible
121171
to identify the key, and to determine later whether the key is still in use or should be removed.
122-
It should be as clear and complete as possible. The duration determines the lifetime of the key
123-
after which the the key becomes invalid. It is recommended to set a short duration (typically 1 day)
124-
for interactive usage. It is not possible to create keys that last for more than 3 months, it means
125-
that long lasting keys must be rotated at least once every 3 months.
172+
The duration determines the lifetime of the key after which the the key becomes invalid. It is
173+
recommended to set a short duration (typically 1 day) for interactive usage. It is not possible to
174+
create keys that last for more than 3 months, it means that long lasting keys must be rotated at
175+
least once every 3 months.
126176

127-
The :guilabel:`Generate Key` creates a 20 bytes (160 bits) strong random key. Its value appears on
128-
screen, this is the only time and place the key is visible on screen, it must be copied, kept secret and stored somewhere secure. If it ever gets compromized or lost, then it must be removed.
177+
The :guilabel:`Generate Key` creates a 160 bits strong random key. Its value appears on screen, this
178+
is the only time and place the key is visible on screen. It must be copied, kept secret and stored
179+
somewhere secure. If it ever gets compromized or lost, then it must be removed.
129180

130181
Please refer to OWASP's `Secrets Management Cheat Sheet`_ for further guidance on the management of
131182
API keys.
@@ -137,8 +188,7 @@ Access Rights
137188
=============
138189

139190
The JSON-2 API uses the standard :ref:`security <reference/security>` model of Odoo. All operations
140-
are validated against the access rights, record rules and field accesses granted to the current
141-
user. The current user is used as well for the :ref:`reference/fields/automatic/log_access`.
191+
are validated against the access rights, record rules and field accesses of the user.
142192

143193
For **interfactive usage**, such as discovering the API or running one-time scripts, it is fine to
144194
use a **personal account**.
@@ -151,12 +201,23 @@ Using dedicated bot users has several benefits:
151201
* The minimum required permissions can be granted to the bot, limiting the impact may the API key
152202
gets compromised;
153203
* The password can be set empty to disable login/password authentication, limiting the likelihood
154-
the account get compromized;
155-
* The :ref:`reference/fields/automatic/log_access` use the bot account. No internal user gets
156-
impersonalized.
204+
the account gets compromized;
205+
* The :ref:`reference/fields/automatic/log_access` use the bot account. No user gets impersonalized.
206+
207+
208+
Database
209+
========
210+
211+
Depending on the deploiement, the ``Host`` and/or ``X-Odoo-Database`` request headers might be
212+
required. The ``Host`` header is required on servers where Odoo is installed next to other web
213+
applications, so a web-server/reverse-proxy is able to route the request to the Odoo server. The
214+
``X-Odoo-Database`` header is required when a single Odoo server hosts multiple databases, and that
215+
:ref:`dbfilter` wasn't configured to use the ``Host`` header.
216+
217+
Most HTTP client libraries automatically set the ``Host`` header using the connection url.
157218

158219

159220
Transaction
160221
===========
161222

162-
.. TODO
223+

0 commit comments

Comments
 (0)