Merge pull request #840 from OpenSPP/fix-description

Update module description

Author: jeremi

spp_api/__manifest__.py

@@ -2,7 +2,7 @@
 
 {
     "name": "OpenSPP API",
-    "summary": "Provides a framework for building and managing a RESTful API for the OpenSPP platform, including API definition, documentation, security, and logging.",
+    "summary": "Establishes a RESTful API framework for OpenSPP, allowing external systems to securely read, create, update, and delete platform data. Customizable API endpoints, robust authentication, comprehensive logging, and flexible data field mapping enhance integration and auditing capabilities.",
     "category": "OpenSPP",
     "images": [
         "images/icon.png",

spp_api/readme/DESCRIPTION.md

@@ -1,52 +1,63 @@
 # 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:
+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.
 
-- **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.
+Together, these integrations allow `spp_api` to provide a secure, functional, and extensible API layer for the entire OpenSPP platform.
 
-## Dependencies
+## Additional Functionality
 
-- **[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.
+The `spp_api` module offers a range of features to configure and manage API interactions effectively.
 
-## Functionality and Integration
+### API Namespace and Endpoint Configuration
 
-The [spp_api](spp_api) module introduces key components for building a robust API:
+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:
 
-**1. API Namespaces and Paths:**
+*   **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.
 
-- **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.
+### Data Field Customization
 
-**2. API Documentation:**
+To simplify integration, the module allows granular control over how data fields appear in the API:
 
-- **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.
+*   **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.
 
-**3. API Security:**
+### API Security and Logging
 
-- **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. 
+The module provides essential tools for securing and monitoring API usage:
 
-**4. API Logging:**
+*   **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.
 
-- **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).
+### Advanced API Operations
 
-**5. Integration with Other Modules:**
+Beyond standard CRUD (Create, Read, Update, Delete) operations, the module supports custom API functions:
 
-- 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.
+*   **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.

spp_api_records/__manifest__.py

@@ -1,6 +1,6 @@
 {
     "name": "OpenSPP API Records",
-    "summary": """Provides RESTful API endpoints for accessing and managing OpenSPP's core data, including service points, programs, products, and entitlements.""",
+    "summary": "It exposes RESTful API endpoints, enabling external systems to programmatically access and manage OpenSPP's core operational data. These endpoints facilitate querying, creating, updating, and deleting records for entities like service points, social protection programs, product definitions, and beneficiary entitlements.",
     "category": "OpenSPP",
     "version": "17.0.1.3.1",
     "author": "OpenSPP.org",