Changes for doc/architecture/helper/helper.md: 82 added lines, 18 removed lines.
Original line number
Diff line number
Diff line
@@ -2,30 +2,94 @@
## Overview
CAPIF does not include any built-in mechanism to expose data via API. This makes it difficult to retrieve essential information such as the number of registered API Invokers, a list of available API Invokers, etc.
The Helper Service is a component of the OpenCAPIF Core that extends CAPIF with functionality not defined in the 3GPP specifications. It runs alongside the CAPIF API services and provides a set of sub-services, each responsible for a specific domain.
Without a dedicated tool, accessing this data requires direct database queries, making it inefficient and impractical.
The Helper Service is built on a modular architecture: each sub-service is defined from its own OpenAPI specification and registered in the Helper's `config.yaml` under the `package_paths` section. When the Helper server starts, it automatically loads and exposes every registered sub-service under its configured base path.
## Helper Service
Currently the Helper exposes four sub-services:
The Helper Service addresses this limitation by acting as an intermediary that exposes CAPIF’s stored data in a structured and accessible manner. This service provides APIs that allow users to query the CAPIF database and obtain valuable insights, such as:
| Sub-service | Base path | Purpose |
|---|---|---|
| **Helper API** | `/api` | Query CAPIF stored data (invokers, providers, services, events, security contexts) and delete entities. |
| **Dynamic Configuration** | `/configuration` | Retrieves and modifies CAPIF configuration stored in MongoDB, without requiring redeployment. |
| **Interconnection** | `/interconnection` | Manages CAPIF interconnection between two CCFs: establishment, teardown and synchronization. |
| **Visibility Control** | `/visibility-control` | Allows providers and administrators to define rules that filter which APIs are discoverable by which invokers. |
- The total count and details of registered API Invokers and API Providers.
- A structured and API-driven way to retrieve CAPIF-related information.
- Simplified access to important data without the need for direct database interactions.
- Access to security contexts, helping manage authentication and authorization processes.
- Retrieval of event records, providing insight into CAPIF system activities.
- The ability to delete different CAPIF entities, facilitating resource management.
- Full control over CAPIF dynamic configuration, including:
- Retrieving the current configuration.
- Modifying specific parameters.
- Adding or updating configuration settings dynamically.
---
Through this Helper Service, CAPIF users can effortlessly retrieve and manage critical system information, improving overall visibility and efficiency.
## Sub-services
### Helper API (`/api`)
## API Documentation
This is the original Helper sub-service. It acts as an intermediary that exposes CAPIF's stored data through a structured API, removing the need for direct database access.
For a detailed API reference, please check the **Helper Service Swagger Documentation**:
It provides the following operations:
➡️ [Helper Service API Documentation](./swagger.md)
-**`GET /getInvokers`** — Retrieve all onboarded API invokers and their details.
-**`GET /getProviders`** — Retrieve all registered API providers and their details.
-**`GET /getServices`** — Retrieve all published service APIs.
-**`GET /getSecurity`** — Retrieve all security contexts (authentication and authorization associations).
-**`GET /getEvents`** — Retrieve all event subscriptions registered in CAPIF.
-**`DELETE /deleteEntities/{uuid}`** — Remove all entities (invokers, providers, services, security contexts, event subscriptions) belonging to a given user UUID.
Access to these endpoints requires a superadmin certificate.
➡️ [Helper API Swagger](./helper-api-swagger.md)
### Dynamic Configuration (`/configuration`)
This sub-service manages CAPIF configuration dynamically, using MongoDB as the configuration store. Changes take effect without restarting or redeploying CAPIF.
It provides the following operations:
-**`GET /getConfiguration`** — Retrieve the current CAPIF configuration.
-**`POST /addNewConfiguration`** — Add an entirely new configuration (replaces the current one).
-**`PUT /replaceConfiguration`** — Replace the current configuration with a new one.
-**`POST /addNewConfigSetting`** — Add a new configuration parameter or section to the existing configuration.
-**`PUT /updateConfigParam`** — Modify the value of a specific configuration parameter.
-**`DELETE /removeConfigParam`** — Remove a specific parameter from a configuration section.
-**`DELETE /removeConfigCategory`** — Remove an entire configuration section.
For more details, see the [Dynamic Configuration feature documentation](../../features/configuration/configuration.md).
This sub-service implements the CAPIF Interconnection capability, allowing two CCFs — either in the same or different trust domains — to interact and share APIs. It manages the lifecycle of an interconnection relationship between a local CCF and a peer CCF.
It provides the following operations:
-**`POST /request`** — Initiate an interconnection request to a peer CCF.
-**`DELETE /request/{ccf_id}`** — Tear down an interconnection with a peer CCF.
-**`POST /establish`** — Called by the requesting CCF on the peer to complete the interconnection handshake.
-**`DELETE /establish/{ccf_id}`** — Called by the requesting CCF on the peer to remove the interconnection.
-**`POST /sync`** — Synchronize published APIs between the two interconnected CCFs.
For more details, see the [Interconnection feature documentation](../../features/interconnection/interconnection.md).
This sub-service allows API Providers and administrators to define fine-grained rules that control API discoverability. When an API Invoker performs a discovery request, the Visibility Control service evaluates the active rules and filters the result set so the invoker only sees APIs they are authorized to access.
It provides the following operations:
-**`GET /rules`** — List all visibility rules.
-**`POST /rules`** — Create a new visibility rule.
-**`GET /rules/{ruleId}`** — Retrieve a specific rule.
-**`PATCH /rules/{ruleId}`** — Partially update a rule.
-**`DELETE /rules/{ruleId}`** — Delete a rule.
-**`GET /decision/invokers/{apiInvokerId}/discoverable-apis`** — Evaluate all active rules and return the list of APIs the given invoker is authorized to discover.
-**`POST /decision/invokers/{apiInvokerId}/discoverable-apis`** — Same as GET, accepting a list of service API descriptions to filter.
For more details, see the [Visibility Control feature documentation](../../features/visibility-control/visibility-control.md).
➡️ [Helper Visibility Control Swagger](./helper-visibility-control-swagger.md)
---
## Adding new sub-services
The Helper's modular design makes it straightforward to add new sub-services. See the [Dynamic Services](./dynamic-services.md) guide for step-by-step instructions on generating a new service from an OpenAPI specification and registering it in the Helper.
