[19.0][ADD] endpoint_json2

endpoint_json2/README.rst

@@ -0,0 +1,217 @@
+.. image:: https://odoo-community.org/readme-banner-image
+   :target: https://odoo-community.org/get-involved?utm_source=readme
+   :alt: Odoo Community Association
+
+==============
+Endpoint JSON2
+==============
+
+.. 
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! This file is generated by oca-gen-addon-readme !!
+   !! changes will be overwritten.                   !!
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! source digest: sha256:4be5f733f68c5063e822982d56dcdf0333d9051dc163bf7d83557dd2f229ebe9
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. |badge1| image:: https://img.shields.io/badge/maturity-Alpha-red.png
+    :target: https://odoo-community.org/page/development-status
+    :alt: Alpha
+.. |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_json2
+    :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_json2
+    :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|
+
+Adds ``exec_mode="json2"`` to the endpoint framework, enabling
+declarative JSON-2 API endpoint configuration. Select a model, method,
+and parameters — the module handles dispatch, parameter validation,
+access control, and result filtering. A code snippet can be used as an
+alternative to a model method for quick, ad-hoc logic.
+
+Also provides auto-generated API documentation endpoints at
+``/json2/doc``.
+
+.. IMPORTANT::
+   This is an alpha version, the data model and design can change at any time without warning.
+   Only for development or testing purpose, do not use in production.
+   `More details on development status <https://odoo-community.org/page/development-status>`_
+
+**Table of contents**
+
+.. contents::
+   :local:
+
+Configuration
+=============
+
+Go to *Settings > Technical > Endpoints* and create a new endpoint with
+**Exec Mode** set to **JSON-2 API**.
+
+Basic Setup
+-----------
+
+-  **Route Group** and **Name**: Together these determine the endpoint
+   URL, which is automatically computed as
+   ``/json2/{route_group}/{name}``. For example, a route group
+   ``contacts`` with name ``get_partners`` produces
+   ``/json2/contacts/get_partners``. The route group also organizes
+   endpoints in the API documentation at ``/json2/doc/{route_group}``.
+
+-  **Model**: The Odoo model to operate on (e.g. ``res.partner``).
+
+-  **Method**: A public model method (e.g. ``search_read``).
+   Alternatively, provide a **Code Snippet** for custom logic — these
+   two fields are mutually exclusive.
+
+-  **Response Fields**: One field per line. Optionally follow with an
+   alias to rename the key in the response. Use dotted notation (one
+   level) for relational fields (Many2one, Many2many, One2many). Leave
+   empty to return all fields. Example:
+
+   ::
+
+      name
+      email
+      country_id.name country
+      write_date last_modified
+
+-  **Default Domain**: A JSON-formatted domain filter applied to every
+   request (e.g. ``[["active", "=", true]]``).
+
+-  **Response Language**: Optionally force a language on the execution
+   context so that translatable field values (including dotted
+   relational fields such as ``uom_id.name``) are returned in that
+   language regardless of the API user's language setting. Untranslated
+   values fall back to the source language.
+
+-  **Response Timezone**: The timezone datetime values are rendered in.
+   Datetimes are always serialized as ISO 8601 with a UTC offset (e.g.
+   ``2026-07-27T13:30:00+09:00``), so this setting only selects the
+   offset they carry; leave it empty to render in UTC. Incoming datetime
+   parameters are not converted — handle request-side conversion in the
+   calling system or a custom method.
+
+-  **Parameters**: Define named parameters with types, defaults, and
+   required flags. These are validated before the method is called.
+
+Access Control
+--------------
+
+All endpoint execution is wrapped in ``sudo()``, allowing API users to
+operate with minimal Odoo privileges. Access is controlled at two
+levels:
+
+-  **Auth Type**: Select the authentication method for the endpoint
+   (e.g. **Bearer** for API key authentication).
+-  **Allowed Groups**: Restrict endpoint access to specific user groups.
+   Create integration-specific groups (e.g. "Hospital System", "WMS")
+   and assign them to the corresponding API users. Each endpoint
+   declares which groups may call it, and at least one group is
+   required: an endpoint that allows no group denies every caller and is
+   hidden from the API documentation.
+
+Code Snippets
+-------------
+
+As an alternative to a model method, a code snippet can be used for
+quick, ad-hoc logic. Available variables:
+
+-  ``Model``: The target model (with ``sudo()``).
+-  ``params``: Validated parameters from the request.
+-  ``env``: The Odoo environment.
+-  ``Command``: Odoo's ``Command`` helper for relational field writes.
+-  ``json``: Safe JSON module for serialization.
+-  ``exceptions``: Werkzeug exceptions (``BadRequest``, ``NotFound``,
+   etc.).
+-  ``log``: Log messages to the ``ir.logging`` table.
+
+The snippet must set a ``result`` variable with the response data.
+
+Usage
+=====
+
+Calling an Endpoint
+-------------------
+
+Send a POST request with a JSON body to the endpoint's route. The
+example below uses Bearer authentication with an API key:
+
+.. code:: bash
+
+   curl -X POST https://your-odoo.com/json2/contacts/get_partners \
+     -H "Content-Type: application/json" \
+     -H "Authorization: Bearer YOUR_API_KEY" \
+     -d '{"domain": [["is_company", "=", true]], "limit": 10}'
+
+API Documentation
+-----------------
+
+Auto-generated documentation for all JSON-2 endpoints is available at
+``/json2/doc``, grouped by route group. Each endpoint's visibility
+respects the **Allowed Groups** setting — users only see endpoints they
+have access to. Filter by route group with ``/json2/doc/{route_group}``.
+
+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_json2%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
+-------
+
+* Quartile
+
+Contributors
+------------
+
+-  Quartile <https://www.quartile.co>
+
+   -  Yoshi Tashiro
+   -  Aung Ko Ko Lin
+   -  Shinnosuke Morita
+
+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-yostashiro| image:: https://github.com/yostashiro.png?size=40px
+    :target: https://github.com/yostashiro
+    :alt: yostashiro
+.. |maintainer-aungkokolin1997| image:: https://github.com/aungkokolin1997.png?size=40px
+    :target: https://github.com/aungkokolin1997
+    :alt: aungkokolin1997
+
+Current `maintainers <https://odoo-community.org/page/maintainer-role>`__:
+
+|maintainer-yostashiro| |maintainer-aungkokolin1997| 
+
+This module is part of the `OCA/web-api <https://github.com/OCA/web-api/tree/19.0/endpoint_json2>`_ project on GitHub.
+
+You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.

endpoint_json2/__init__.py

@@ -0,0 +1,2 @@
+from . import controllers
+from . import models

endpoint_json2/__manifest__.py

@@ -0,0 +1,20 @@
+# Copyright 2026 Quartile (https://www.quartile.co)
+# License LGPL-3.0 or later (https://www.gnu.org/licenses/lgpl).
+{
+    "name": "Endpoint JSON2",
+    "summary": "Declarative JSON-2 API endpoints on the endpoint stack",
+    "version": "19.0.1.0.0",
+    "license": "LGPL-3",
+    "development_status": "Alpha",
+    "author": "Quartile, Odoo Community Association (OCA)",
+    "website": "https://github.com/OCA/web-api",
+    "category": "Technical",
+    "depends": ["endpoint"],
+    "data": [
+        "security/ir.model.access.csv",
+        "views/endpoint_views.xml",
+    ],
+    "demo": ["demo/endpoint_json2_demo.xml"],
+    "installable": True,
+    "maintainers": ["yostashiro", "aungkokolin1997"],
+}

endpoint_json2/controllers/__init__.py

@@ -0,0 +1 @@
+from . import main

endpoint_json2/controllers/main.py

@@ -0,0 +1,70 @@
+# Copyright 2026 Quartile (https://www.quartile.co)
+# License LGPL-3.0 or later (https://www.gnu.org/licenses/lgpl).
+
+from werkzeug.exceptions import NotFound
+
+from odoo import http
+from odoo.fields import Domain
+from odoo.http import request
+
+
+class EndpointJson2DocController(http.Controller):
+    def _get_accessible_endpoints(self, extra_domain=Domain.TRUE):
+        domain = Domain("exec_mode", "=", "json2") & extra_domain
+        all_endpoints = request.env["endpoint.endpoint"].sudo().search(domain)
+        user = request.env.user
+        return all_endpoints.filtered(
+            lambda ep: ep.json2_group_ids & user.all_group_ids
+        )
+
+    def _endpoint_to_doc(self, endpoint):
+        return {
+            "name": endpoint.name,
+            "description": endpoint.json2_description or "",
+            "method": endpoint.json2_method,
+            "model": endpoint.json2_model_name,
+            "url": endpoint.route,
+            "parameters": [
+                {
+                    "name": p.name,
+                    "type": p.param_type,
+                    "required": p.required,
+                    "description": p.description or "",
+                    "default": p.default_value,
+                }
+                for p in endpoint.json2_param_ids
+            ],
+        }
+
+    @http.route(
+        "/json2/doc",
+        methods=["GET"],
+        auth="user",
+        type="http",
+        readonly=True,
+        save_session=False,
+    )
+    def doc_index(self):
+        endpoints = self._get_accessible_endpoints()
+        result = {}
+        for ep in endpoints:
+            result.setdefault(ep.route_group, []).append(self._endpoint_to_doc(ep))
+        return request.make_json_response(result)
+
+    @http.route(
+        "/json2/doc/<string:route_group>",
+        methods=["GET"],
+        auth="user",
+        type="http",
+        readonly=True,
+        save_session=False,
+    )
+    def doc_domain(self, route_group):
+        endpoints = self._get_accessible_endpoints(
+            Domain("route_group", "=", route_group)
+        )
+        if not endpoints:
+            raise NotFound(f"No endpoints found for domain {route_group!r}")
+        return request.make_json_response(
+            [self._endpoint_to_doc(ep) for ep in endpoints]
+        )