Newer
Older
The OpenCAPIF SDK facilitates the integration of applications with the CAPIF NF. It offers various features for manual usage, automated scripting, and direct integration into application code.
This documentation provides a step-by-step guide for utilizing the SDK, detailing its functionalities. Before proceeding, ensure all prerequisites are met, and review the available testing modes for the SDK.
Before using the SDK, the following steps should be completed:
- Meet the [requirements](../README.md),
- Follow the [installation instructions](./sdk_developers.md),
- Configure the SDK by completing the relevant sections in the [configuration guide](./sdk_configuration.md), depending on the CAPIF role the Network App will assume.
The repository provides two modes for utilizing the OpenCAPIF SDK:
1. **Development Mode**: The SDK can be imported directly into code for development purposes. Sample applications using the SDK are available in the [network_app_samples](../network_app_samples/) folder.
2. **Manual Mode**: A set of Python [scripts](../scripts/) can be used to manually test each integration step. For manual usage, it is necessary to complete the utilities file with absolute paths from the target environment to finalize SDK configuration.
**IMPORTANT**: All SDK configuration files must be filled out based on the intended role and features. Further details can be found in the [Configuration Section](./sdk_configuration.md).
**NOTE**: The register file is not required for SDK usage, only for SDK consumers that wish to create their `capif_username`.
As outlined in the [Network App developers section](../README.md), the OpenCAPIF SDK supports two primary roles:
- [Provider Network App](#provider-network-app)
- [Important Information for Providers](#important-information-for-providers)
- [Provider Onboarding](#provider-onboarding)
- [Service Publishing](#service-publishing)
- [Service Deletion](#service-deletion)
- [Service Updates](#service-update)
- [Get Published Services](#get-services)
- [Get All Published Services](#get-all-services)
- [Update and Offboard Provider](#update-and-offboard-provider)
- [Important Information for Invokers](#important-information-for-invokers)
- [Invoker Onboarding](#invoker-onboarding)
- [Service Discovery](#service-discovery)
- [Obtain JWT Tokens](#obtain-jwt-tokens)
- [Check authentication](#check-authentication)
- [Update and Offboard Invoker](#update-and-offboard-invoker)
- [Other Features](#other-features)
- [Openapi translation](#openapi-translation)
- [CAPIF Registration and Login](#capif-registration-and-login)
- [CAPIF Deregistration and Logout](#capif-registration-and-login)
The OpenCAPIF SDK enables efficient implementation of invoker functionality for Network App. This section details the SDK features related to CAPIF providers.
Within the `provider_folder`, directories are created based on the registered `capif_username`. Each folder contains:
- `provider_service_ids.json`: Contains all APFs and AEFs IDs onboarded with the associated username.
- `capif_<api_name>_<api_id>.json`: Stores the last payload for any published or updated API.
- `service_received.json`: Stores responses for Get API or Get All APIs.
- `provider_capif_ids.json`: A list of currently published APIs along with their IDs.
All the configuration values are available within the object capif_provider_connector.
The provider_capif_ids variable stores the `provider_service_ids.json` content in a dictionary form.
### Provider Onboarding
OpenCAPIF SDK references:
- **Function**: `onboard_provider()`
- **Script**: `provider_capif_connector.py`
The SDK simplifies the onboarding process, allowing providers to register multiple APFs and AEFs. All APFs, AEFs, and AMF certificates are created and stored in `provider_service_ids.json`.
### Service Publishing
OpenCAPIF SDK references:
- **Function**: `publish_services()`
- **Script**: `provider_publish_api.py`
The SDK streamlines API publishing with the option to select specific APFs and AEFs. A copy of the uploaded API is stored in `capif_<api_name>_<api_id>.json`, and the `provider_capif_ids.json` is updated with the API name and its ID.
It is also important to have previously prepared the **API schema description** file of the API to be published. **This file must follow the [CAPIF_Publish_Service_API](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Publish_Service_API.yaml) 3GPP specification.**
To obtain this schema, opencapif_sdk has a facility to translate Openapi structures to ServiceAPIDescription schemas.
More information:[Translator functionality](#openapi-translation)
**Important**: The SDK will automatically add in the `custom operations`, within the API description path, the capabilities for exposing the [AEF_security](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_AEF_Security_API.yaml) methods. The developer must code this API endpoints.
**Required SDK inputs**:
- publisher_apf_id
- publisher_aefs_ids
- api_description_path
- **Function**: `unpublish_service()`
- **Script**: `provider_unpublish_api.py`
The SDK simplifies API deletion. Service deletion requires prior onboarding and service publication.
**Required SDK inputs**:
- publisher_apf_id
- publisher_aefs_ids
OpenCAPIF SDK references:
- **Function**: `update_service()`
- **Script**: `provider_update_api.py`
This function enables to update a previously registered API. Selecting APFs and AEFs is possible. Onboarding and service publishing are prerequisites.
- service_api_id
- publisher_apf_id
- publisher_aefs_ids
### Get Services
OpenCAPIF SDK references:
- **Function**: `get_service()`
- **Script**: `provider_get_published_api.py`
Retrieve information of a previously published service, stored in `service_received.json`. Prior onboarding and service publication are necessary.
OpenCAPIF SDK references:
- **Function**: `get_all_services()`
- **Script**: `provider_get_all_published_api.py`
Retrieve information about all previously published services in `service_received.json`. Ensure you are [onboarded as a provider](#provider-onboarding) and have [published services](#services-publishing).
**Required SDK input**:
- publisher_apf_id
### Update and Offboard Provider
OpenCAPIF SDK references:
- **Functions**: `update_provider()` and `offboard_provider()`
- **Scripts**: `provider_capif_connector_update.py` and `provider_capif_connector_offboarding.py`
`update_provider()`: The provider updates his features such as `APFs`, `AEFs`, etc...
`offboard_provider()`: The provider offboards from CAPIF, this will cause the erase of the published APIs that were currently exposed.
The provider must be onboarded before using these features.
The OpenCAPIF SDK enables efficient implementation of invoker functionality for Network App. This section details the SDK features related to CAPIF invokers.
### Important Information for Invokers
Within the `invoker_folder`, directories are created based on the registered `capif_username`. These directories contain:
- `capif_api_security_context_details.json`: Stores details about the invoker, including:
1. `api_invoker_id`
2. Discovered APIs and their information (if Service Discovery has been used)
3. JWT access tokens for discovered APIs (if Service Get Token functionality has been used)
The `token` variable is also available for retrieving the JWT token after the get_tokens() functionality.
The invoker_capif_details variable stores the `capif_api_security_context_details.json` content.
OpenCAPIF SDK references:
- **Function**: `onboard_invoker()`
- **Script**: `invoker_capif_connector.py`
The SDK streamlines the invoker onboarding process, storing the `api_invoker_id` in the `capif_api_security_context_details.json`.
### Service Discovery
OpenCAPIF SDK references:
- **Function**: `discover()`
- **Script**: `invoker_service_discover.py`
The [discover_filter](./sdk_configuration.md) can be used to retrieve access to APIs. The invoker must be onboarded before using this function. Discovered APIs and their information are stored in `capif_api_security_context_details.json`.
**Note**: A 404 warning may be received during the first discovery run, prompting registration for the security service.
Use the [discover_filter](./sdk_configuration.md) to retrieve access to target APIs. Ensure you are [onboarded as an invoker](#invoker-onboarding) before using this feature.
### Obtain JWT Tokens
OpenCAPIF SDK references:
- **Function**: `get_tokens()`
- **Script**: `invoker_service_get_token.py`
The SDK facilitates JWT token creation for secure access to target APIs. This process stores JWT access token in `capif_api_security_context_details.json`.
### Check authentication
OpenCAPIF SDK references:
- **Function**: `check_authentication()`
The SDK allows the Network App Invoker to check the `supported_features` from the target Provider's API exposing function (AEF).
It is mandatory to have obtained the [JWT token](#obtain-jwt-tokens) previously.
### Update and Offboard Invoker
OpenCAPIF SDK references:
- **Functions**: `update_invoker()` and `offboard_invoker()`
- **Scripts**: `invoker_capif_connector_update.py` and `invoker_capif_connector_offboarding.py`
Onboarding is required before utilizing these functions.
## Other Features
### Openapi translation
The `api_description_path` must point to the Publish API to be shared, and it should follow the [ServiceAPIDescription](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Publish_Service_API.yaml) schema.
This schema could be obtained by applying this code.
```python
import opencapif_sdk
translator = opencapif_sdk.api_schema_translator("./path/to/openapi.yaml")
translator.build("api_description_name",ip="0.0.0.0",port=9090)
```
This code will read `openapi.yaml`, ensure the structure of it and translate the content into ServiceAPIDescription schema, then will create a .json named `api_description_name`. Also it is necessary to fill the ip and port fields to create correctly the schema.
Simplifies the login process for admin users and creates a CAPIF user.
* **Script**: `deregister_and_login.py`
Simplifies the logout process for admin users and removes a CAPIF user.
