docs: remove Graphviz directive and MyST fences from fragments; regenerate all addon READMEs

Author: jeremi

spp_api/README.rst

@@ -7,7 +7,7 @@ OpenSPP API
    !! This file is generated by oca-gen-addon-readme !!
    !! changes will be overwritten.                   !!
    !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-   !! source digest: sha256:b2fcfd7a69f544f8f19fc307b5cd87170138d8fc625affae1b087d26d428644f
+   !! source digest: sha256:0ea93f9033fbf7741a23baa3a9ea398ff1bd54e97f630c4287ef18bc2a4407a2
    !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 .. |badge1| image:: https://img.shields.io/badge/maturity-Production%2FStable-green.png
@@ -25,102 +25,140 @@ OpenSPP API
 OpenSPP API
 ===========
 
-Overview
---------
-
-The `spp_api <spp_api>`__ module provides a comprehensive framework for
-building and managing a RESTful API for the OpenSPP platform. It builds
-upon the foundation laid by the `spp_base_api <spp_base_api>`__ module,
-adding crucial components for API definition, documentation, and
-security.
+The OpenSPP API module provides a robust framework for building and
+managing a RESTful API (Application Programming Interface) for the
+OpenSPP platform. It enables external systems and applications to
+securely interact with OpenSPP data and functionalities, facilitating
+seamless integration, data exchange, and automation.
 
 Purpose
 -------
 
-This module is designed to:
-
--  **Define API Endpoints:** Create, configure, and manage API endpoints
-   for accessing and manipulating data within the OpenSPP system.
--  **Generate API Documentation:** Automatically generate OpenAPI
-   (Swagger) documentation for all defined API endpoints, providing a
-   clear and interactive interface for developers.
--  **Enforce API Security:** Integrate with the
-   `spp_oauth <spp_oauth>`__ module to handle authentication and
-   authorization for API requests, ensuring secure access to sensitive
-   data.
--  **Log API Interactions:** Record details of all incoming API requests
-   and outgoing responses, facilitating debugging, monitoring, and
-   auditing.
-
-Dependencies
-------------
-
--  `spp_base_api <spp_base_api>`__\ **:** This module relies on
-   `spp_base_api <spp_base_api>`__ for its core API interaction
-   functions and methods.
--  **web:** Leverages Odoo's web framework for routing and handling HTTP
-   requests.
--  `spp_oauth <spp_oauth>`__\ **:** Integrates with the
-   `spp_oauth <spp_oauth>`__ module to implement OAuth 2.0-based
-   authentication and authorization for securing API access.
-
-Functionality and Integration
------------------------------
-
-The `spp_api <spp_api>`__ module introduces key components for building
-a robust API:
-
-**1. API Namespaces and Paths:**
-
--  **Namespaces:** Represent logical groupings of API endpoints, often
-   associated with specific functionalities or versions (e.g., ``v1``,
-   ``v2``).
--  **Paths:** Define individual API endpoints within a namespace,
-   specifying the HTTP method (GET, POST, PUT, DELETE, PATCH), URL path,
-   data model, fields to expose, and any filtering or domain logic.
-
-**2. API Documentation:**
-
--  **OpenAPI (Swagger) Generation:** The module automatically generates
-   OpenAPI documentation based on the defined namespaces and paths. This
-   documentation serves as a comprehensive guide for developers,
-   detailing available endpoints, request/response formats, and
-   authentication requirements.
-
-**3. API Security:**
-
--  **OAuth 2.0 Integration:** Seamlessly integrates with
-   `spp_oauth <spp_oauth>`__ to enforce authentication and authorization
-   using OAuth 2.0 standards. API requests must include valid access
-   tokens, obtained through the OAuth 2.0 flow.
-
-**4. API Logging:**
-
--  **Detailed Logs:** Records comprehensive logs for all API
-   interactions, including the request method, URL, parameters, data,
-   response status code, and response data.
--  **Configurable Logging Levels:** Allows administrators to configure
-   the level of detail logged for requests and responses (e.g.,
-   disabled, short, full debug).
-
-**5. Integration with Other Modules:**
-
--  Any OpenSPP module that wants to expose data or functionalities
-   through an API can leverage the `spp_api <spp_api>`__ module.
--  Modules define their API endpoints using namespaces and paths,
-   ensuring consistency and automatic documentation generation.
--  The `spp_api <spp_api>`__ module handles routing, authentication, and
-   logging for these endpoints, simplifying development and ensuring API
-   security.
+This module serves as the central hub for OpenSPP's external
+communication, offering a structured way to expose and manage platform
+capabilities. It accomplishes the following key objectives:
+
+-  **Standardized Data Access:** Establishes a consistent and secure
+   method for external applications to read, create, update, and delete
+   OpenSPP data, such as beneficiary records or program details.
+-  **Customizable API Endpoints:** Allows users to define specific API
+   endpoints for various OpenSPP data models and operations, tailoring
+   the API to the exact needs of integrated systems.
+-  **Enhanced Security:** Implements authentication and authorization
+   mechanisms to ensure that only authorized users and systems can
+   access and manipulate sensitive program information.
+-  **Comprehensive Logging and Auditing:** Provides detailed logging of
+   all API interactions, offering transparency, aiding in
+   troubleshooting, and supporting compliance requirements.
+-  **Flexible Data Mapping:** Enables the renaming and configuration of
+   data fields exposed through the API, making integration simpler and
+   more intuitive for external systems.
+
+Dependencies and Integration
+----------------------------
+
+The ``spp_api`` module is foundational to OpenSPP's external
+connectivity, building upon other core modules to deliver its
+capabilities:
+
+-  It leverages the `OpenSPP Base API <spp_base_api>`__ module, which
+   provides essential, low-level API functions and methods for
+   interacting with OpenSPP models. This ensures a consistent foundation
+   for all API operations.
+-  Security for API access is handled by the `OpenSPP API:
+   Oauth <spp_oauth>`__ module, which implements secure authentication
+   protocols and token management. This module ensures that all API
+   requests are properly authorized before accessing OpenSPP resources.
+-  The module integrates with the core ``mail`` module, likely for
+   sending notifications or alerts related to API activities or issues.
+-  It utilizes the ``web`` module for exposing API endpoints over the
+   web, making them accessible to external applications.
+
+Together, these integrations allow ``spp_api`` to provide a secure,
+functional, and extensible API layer for the entire OpenSPP platform.
+
+Additional Functionality
+------------------------
+
+The ``spp_api`` module offers a range of features to configure and
+manage API interactions effectively.
+
+API Namespace and Endpoint Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users can define distinct API namespaces to group related endpoints,
+manage versions, and control access. Each namespace acts as a unique
+integration point, such as 'Beneficiary_Service_v1' or
+'Financial_Aid_v2'. Within these namespaces, specific API paths
+(endpoints) are created for individual OpenSPP data models (e.g.,
+"Beneficiary", "Program"). For each path, users configure:
+
+-  **Supported Operations:** Define whether external systems can read
+   (GET), create (POST), update (PUT), delete (DELETE), or perform
+   custom (PATCH) actions on the data.
+-  **Data Filtering and Limits:** For read operations, specify default
+   filters (e.g., only active beneficiaries) and set limits on the
+   number of records returned.
+-  **Custom Functions:** Implement custom business logic as API
+   endpoints, complete with defined input parameters.
+
+Data Field Customization
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To simplify integration, the module allows granular control over how
+data fields appear in the API:
+
+-  **Field Selection:** For read operations, specify exactly which
+   fields of an OpenSPP model are exposed, preventing unnecessary data
+   transfer.
+-  **Required Fields and Default Values:** For create and update
+   operations, mark specific fields as mandatory or provide default
+   values, ensuring data consistency.
+-  **Field Aliases:** Rename internal OpenSPP field names to more
+   intuitive, external-facing names within the API. For instance, an
+   internal field like ``b_dob`` (beneficiary date of birth) can be
+   aliased to ``beneficiary_birthdate`` for clarity in the API. These
+   aliases can be global or specific to an API path.
+
+API Security and Logging
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The module provides essential tools for securing and monitoring API
+usage:
+
+-  **User API Tokens:** OpenSPP users can generate unique API tokens to
+   authenticate their external applications. These tokens are essential
+   for secure access to the API.
+-  **Namespace-based Access Control:** Assign specific API namespaces to
+   individual OpenSPP users, granting them access only to the
+   integrations they need.
+-  **Detailed API Logs:** All API requests and responses are logged,
+   including method, model, and the data exchanged. This provides a
+   comprehensive audit trail, crucial for debugging, security
+   monitoring, and compliance. Users can configure logging levels
+   (disabled, short, full) for both requests and responses.
+
+Advanced API Operations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Beyond standard CRUD (Create, Read, Update, Delete) operations, the
+module supports custom API functions:
+
+-  **Custom Function Parameters:** Define specific parameters (e.g.,
+   name, type, required status, default value) for custom API functions,
+   allowing external systems to trigger complex business processes
+   within OpenSPP.
+-  **Record-Specific Actions:** Custom functions can be configured to
+   apply either globally or on specific records, offering flexibility
+   for targeted actions.
 
 Conclusion
 ----------
 
-The `spp_api <spp_api>`__ module is the cornerstone for building and
-managing a secure and well-documented RESTful API for the OpenSPP
-platform. It provides a standardized framework for API development,
-streamlines integration with other modules, and enhances the security of
-OpenSPP data by leveraging OAuth 2.0 authentication.
+The ``spp_api`` module is indispensable for extending OpenSPP's reach,
+enabling secure, flexible, and auditable integration with external
+systems to streamline social protection program management and data
+exchange.
 
 **Table of contents**