Metadata-Version: 2.1
Name: odoo-addon-endpoint
Version: 19.0.1.1.0
Requires-Dist: PyYAML
Requires-Dist: jsonschema
Requires-Dist: odoo-addon-endpoint_route_handler==19.0.*
Requires-Dist: odoo-addon-rpc_helper==19.0.*
Requires-Dist: odoo==19.0.*
Summary: Provide custom endpoint machinery.
Home-page: https://github.com/OCA/web-api
License: LGPL-3
Author: Camptocamp,Odoo Community Association (OCA)
Author-email: support@odoo-community.org
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 19.0
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Development Status :: 4 - Beta
Description-Content-Type: text/x-rst

.. image:: https://odoo-community.org/readme-banner-image
   :target: https://odoo-community.org/get-involved?utm_source=readme
   :alt: Odoo Community Association

========
Endpoint
========

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:f9875b1e57749d28c0d5ce9b07a7259e0a6de3bbf08a126e2d19df824c4325ed
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
    :target: https://odoo-community.org/page/development-status
    :alt: Beta
.. |badge2| image:: https://img.shields.io/badge/license-LGPL--3-blue.png
    :target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
    :alt: License: LGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fweb--api-lightgray.png?logo=github
    :target: https://github.com/OCA/web-api/tree/19.0/endpoint
    :alt: OCA/web-api
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
    :target: https://translation.odoo-community.org/projects/web-api-19-0/web-api-19-0-endpoint
    :alt: Translate me on Weblate
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
    :target: https://runboat.odoo-community.org/builds?repo=OCA/web-api&target_branch=19.0
    :alt: Try me on Runboat

|badge1| |badge2| |badge3| |badge4| |badge5|

Provide an endpoint framework allowing users to define their own custom
endpoint.

Thanks to endpoint mixin the endpoint records are automatically
registered as real Odoo routes.

You can easily code what you want in the code snippet.

NOTE: for security reasons any kind of RPC call is blocked on endpoint
records.

**Table of contents**

.. contents::
   :local:

Configuration
=============

Endpoints are managed under **Technical → Endpoints**.

Each record represents a single HTTP route exposed by Odoo and executed
according to its configuration.

Identification
--------------

- **Name**: human-readable label used in lists and logs.
- **Route**: URL path served by the endpoint (e.g. ``/my/custom/path``).
  Routes must be unique across **all** endpoint-consumer models, not
  only within ``endpoint.endpoint``.
- **Route group**: free-text tag to classify related routes together.
  Useful for filtering and for downstream modules that group endpoints.

Authentication
--------------

- **Auth type**:

  - ``User``: the request must be authenticated as an Odoo user
    (default).
  - ``Public``: the route is accessible without authentication.

- **Exec as user**: the user under which the code snippet runs.

  - **Mandatory** when *Auth type* is ``Public`` (the public user has no
    real privileges, so the endpoint must impersonate a real user to
    perform any meaningful work).
  - Optional otherwise; if set, the snippet is evaluated as that user
    instead of the caller.

Request
-------

- **Request method**: ``GET``, ``POST``, ``PUT`` or ``DELETE``. Requests
  using any other method are rejected with ``405 Method Not Allowed``.

- **Request content type**: expected ``Content-Type`` of the incoming
  request body. Mandatory for ``POST``/``PUT``. Available values:

  - ``text/plain``, ``text/csv``
  - ``application/json``
  - ``application/xml``
  - ``application/x-www-form-urlencoded``

  When set, requests with a different ``Content-Type`` header are
  rejected with ``415 Unsupported Media Type``.

Request content schema (optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For ``POST``/``PUT`` endpoints whose content type is
``application/json`` or ``application/xml``, an optional **Request
Schema** tab is shown. When a schema is provided, the request body is
validated against it before the code snippet runs; on failure, the
request is rejected with a structured validation error
(``RequestValidationError``).

The accepted schema format depends on the content type:

- **JSON** (``application/json``): a JSON Schema (Draft 2020-12). The
  field accepts both JSON and YAML syntax — YAML is convenient when
  authoring schemas inline.
- **XML** (``application/xml``): an XML Schema (XSD).

Example JSON Schema (YAML form):

.. code:: yaml

   type: object
   required: [name, qty]
   properties:
     name: { type: string }
     qty:  { type: integer, minimum: 1 }

Example XSD:

.. code:: xml

   <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="greeting" type="xs:string"/>
   </xs:schema>

..

   **Tip:** when shipping endpoints from a module, the schema can live
   in a separate file and be loaded into the field at install time using
   the ``file`` attribute on the data record:

   .. code:: xml

      <field name="request_content_schema" type="char" file="endpoint/demo/content_schema.xsd" />

Execution
---------

- **Exec mode**: how the request is handled. The base module ships
  ``Execute code``; downstream modules can register additional modes.

- **Code snippet** *(when exec mode is ``code``)*: Python code evaluated
  via ``safe_eval`` for every request. The snippet must assign a
  ``dict`` to the ``result`` variable; it can either contain a
  ready-made ``Response`` (under the ``response`` key) or ``payload``,
  ``headers`` and ``status_code`` to be assembled by the framework.

  Variables exposed to the snippet (see the **Code Help** tab on the
  form for the live, up-to-date list):

  - ``env``, ``user``, ``endpoint``, ``request``
  - ``datetime``, ``dateutil``, ``time``, ``json``
  - ``Response`` (Odoo's ``http.Response``)
  - ``werkzeug`` (limited to ``NotFound``, ``BadRequest``,
    ``Unauthorized``)
  - ``exceptions`` (limited to ``UserError``, ``ValidationError``)
  - ``hashlib``, ``hmac`` (subset of the standard library)
  - ``log(message, level="info")`` — writes to ``ir.logging``

  Raising ``UserError`` or ``ValidationError`` from the snippet is
  converted to ``400 Bad Request``.

Minimal snippet:

.. code:: python

   result = {"response": Response("Hello, World!")}

Registry synchronization
------------------------

Endpoints are registered in a routing registry that lives outside the
ORM. After creating, modifying or archiving a record, the warning
*"Registry out of sync"* appears on the form, and the record is shown in
the **To sync** filter on the list view. Run the **Sync registry**
action to commit the changes to the live routing table — until then, the
new configuration is **not** served.

Known issues / Roadmap
======================

- add api docs generation
- handle multiple routes per endpoint

Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/OCA/web-api/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/OCA/web-api/issues/new?body=module:%20endpoint%0Aversion:%2019.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
-------

* Camptocamp

Contributors
------------

- Simone Orsi <simone.orsi@camptocamp.com>
- Iván Todorovich <ivan.todorovich@camptocamp.com>
- Alex Garcia <alex@studio73.es>

Maintainers
-----------

This module is maintained by the OCA.

.. image:: https://odoo-community.org/logo.png
   :alt: Odoo Community Association
   :target: https://odoo-community.org

OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.

.. |maintainer-simahawk| image:: https://github.com/simahawk.png?size=40px
    :target: https://github.com/simahawk
    :alt: simahawk

Current `maintainer <https://odoo-community.org/page/maintainer-role>`__:

|maintainer-simahawk| 

This module is part of the `OCA/web-api <https://github.com/OCA/web-api/tree/19.0/endpoint>`_ project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
