Merge pull request #63 from OpenSPP/refactor-structure-modify

Fix Headers on API Usage

Author: emjay0921

docs/developer_guide/api_usage/dci_api.md

@@ -15,15 +15,17 @@ OpenSPP provides a RESTful API that adheres to the Digital Convergence Initiativ
 - Client credentials (Client ID and Client Secret) obtained from the OpenSPP instance.
 - Python 3.x and the `requests` library installed (`pip install requests`).
 
-## 1. Authentication: Obtaining an Access Token
+## Process
+
+### Authentication: Obtaining an Access Token
 
 The DCI API is secured using OAuth 2.0 with the Client Credentials grant type. Before making any data requests, your application must obtain a bearer token.
 
 - **Endpoint**: `/oauth2/client/token`
 - **Method**: `POST`
 - **Body**: `x-www-form-urlencoded` with `grant_type`, `client_id`, `client_secret`, `db_name`.
 
-### Example: Get Access Token
+**Example: Get Access Token**
 
 ```python
 import requests
@@ -50,7 +52,7 @@ access_token = token_data.get("access_token")
 print("Access Token obtained successfully.")
 ```
 
-## 2. Searching the Registry
+### Searching the Registry
 
 Once authenticated, you can use the access token to perform a synchronous search on the registry.
 
@@ -61,7 +63,7 @@ Once authenticated, you can use the access token to perform a synchronous search
     - `Content-Type`: `application/json`
 - **Body**: A JSON object conforming to the DCI `sync/search` request specification.
 
-### Example: Search for an Individual
+**Example: Search for an Individual**
 
 ```python
 search_url = f"{url}/registry/sync/search"
@@ -125,7 +127,7 @@ else:
 ```
 
 
-## 3. Setup and Configuration
+### Setup and Configuration
 
 To use the DCI API, you must first configure a client in OpenSPP.
 
@@ -135,15 +137,14 @@ To use the DCI API, you must first configure a client in OpenSPP.
 4.  **Reveal Credentials**: A **Show** button will appear. Click it to reveal the `Client ID` and `Client Secret`.
 5.  **Important**: Copy these credentials immediately. For security, the **Show** button will disappear after you close the dialog, and you will not be able to retrieve the secret again.
 
-## 4. Best Practices
+## Best Practices
 
 1.  **Secure Credential Storage**: Never hard-code your `Client ID` or `Client Secret` in your application. Use environment variables or a secure secret management system.
 2.  **Token Management**: Access tokens are short-lived. Your application should handle token expiration and automatically request a new one when needed.
 3.  **Error Handling**: Implement robust error handling to manage different HTTP status codes and error responses from the API.
 4.  **Secure Connections**: Always use HTTPS for all API traffic to protect data in transit.
 5.  **Logging**: Log request `transaction_id`s and correlation IDs to help with troubleshooting and auditing.
 
-## 5. References
+## References
 
-- [DCI Interface Standards v1.0](https://standards.spdci.org/standards/standards-for-interoperability-interfaces/structure-and-versioning-of-the-standards)
-- [Odoo 17 Developer Documentation](https://www.odoo.com/documentation/17.0/developer/)
+- [DCI Interface Standards v1.0](https://standards.spdci.org/standards/standards-for-interoperability-interfaces/structure-and-versioning-of-the-standards)

docs/developer_guide/api_usage/external_api_jsonrpc.md

@@ -15,14 +15,15 @@ This guide explains how to connect to and interact with OpenSPP Registry using t
 - User credentials or API key with appropriate permissions.
 - Python 3.x and the `requests` library installed (`pip install requests`).
 
-## 1. Understanding JSON-RPC in OpenSPP
+## Process
+### Understanding JSON-RPC in OpenSPP
 
 OpenSPP exposes much of its data and functionality via JSON-RPC endpoints. You can use these endpoints to authenticate, read, create, update, and delete records from external applications.
 
 **Endpoint:**  
 - `/jsonrpc` — All JSON-RPC calls (authentication and model methods)
 
-## 1.1 JSON-RPC Payload Structure and Methods
+### JSON-RPC Payload Structure and Methods
 
 All interactions with the OpenSPP JSON-RPC API use a standard payload structure. Each request is a JSON object with the following keys:
 
@@ -59,11 +60,11 @@ payload = {
 
 ---
 
-## 1.2 Common Model Methods and Args
+### Common Model Methods and Args
 
 When using the `"object"` service with the `"execute_kw"` method, you can call various model methods. Here are the most common:
 
-### `create`
+**`create`**
 Creates a new record.
 
 **Args:**
@@ -79,7 +80,7 @@ Creates a new record.
 **Result:**
 Returns the ID of the newly created record.
 
-### `write`
+**`write`**
 Updates existing records.
 
 **Args:**
@@ -96,7 +97,7 @@ Updates existing records.
 **Result:**
 Returns a dictionary indicating the result of the update.
 
-### `unlink`
+**`unlink`**
 Deletes records.
 
 **Args:**
@@ -113,7 +114,7 @@ Deletes records.
 Returns a dictionary indicating the result of the deletion.
 
 
-### `search_read`
+**`search_read`**
 Searches for records and reads their fields.
 
 **Args:**
@@ -141,7 +142,7 @@ Returns a dictionary of the search results.
 
 ---
 
-## 2. Authentication
+### Authentication
 
 You must authenticate before accessing most data. Use your password or an API key (recommended).
 
@@ -170,9 +171,9 @@ if not uid:
 print("Authenticated UID:", uid)
 ```
 
-## 3. Working with Individuals
+### Working with Individuals
 
-### Gather the Fields
+**Gather The Fields**
 
 For this example we are going to use these fields:
 
@@ -184,7 +185,7 @@ For this example we are going to use these fields:
 - `is_registrant` (boolean, default=True)
 - `is_group` (boolean, default=False)
 
-### Example: Create an Individual
+**Example: Create an Individual**
 
 ```python
 # First, get a gender_id (e.g., for "Male")
@@ -254,9 +255,9 @@ updated = response["result"]
 print("Result:", updated)
 ```
 
-## 4. Working with Groups
+### Working with Groups
 
-### Required Fields
+**Gather The Fields**
 
 For this example we are going to use these fields:
 
@@ -266,7 +267,7 @@ For this example we are going to use these fields:
 - `is_group` (boolean, default=True)
 
 
-### Example: Create a Group
+**Example: Create a Group**
 
 ```python
 # Get a group kind (e.g., "Household")
@@ -333,9 +334,9 @@ updated = response["result"]
 print("Result:", updated)
 ```
 
-## 5. Working with Memberships
+### Working with Memberships
 
-### Required Fields
+**Gather The Fields**
 
 From your `g2p_registry_membership` module, the main model is likely `g2p_registry_membership.group_membership`. Required fields typically include:
 - `individuak` (many2one, required)
@@ -344,7 +345,7 @@ From your `g2p_registry_membership` module, the main model is likely `g2p_regist
 - `start_date` (date, required)
 - Any other required fields as defined in your model
 
-### Example: Add an Individual to a Group
+**Example: Add an Individual to a Group**
 
 ```python
 # Get a membership kind (e.g., "Head")
@@ -391,13 +392,13 @@ membership_id = response["result"]
 print("Created Membership ID:", membership_id)
 ```
 
-## 6. Security: Using API Keys
+### Security: Using API Keys
 
 - **API keys** are recommended over passwords for scripts and integrations.
 - Generate API keys in your OpenSPP user preferences under **Account Security**.
 - Use the API key in place of your password in all JSON-RPC calls.
 
-## 7. Best Practices
+## Best Practices
 
 1. **Use API Keys**: Safer than passwords; revoke if compromised.
 2. **Limit Permissions**: Create dedicated users for API access with only necessary rights.
@@ -408,5 +409,4 @@ print("Created Membership ID:", membership_id)
 ## References
 
 - [Odoo 17 Developer Documentation](https://www.odoo.com/documentation/17.0/developer/)
-- [OpenSPP Developer Guide](https://docs.openspp.org/)
 - [JSON-RPC Specification](https://www.jsonrpc.org/specification)