diff --git a/doc/images/architecture/sdk/flows-capif_illustration.jpg b/doc/images/architecture/sdk/flows-capif_illustration.jpg new file mode 100644 index 0000000000000000000000000000000000000000..8a1c1302980d9386586246b789198fbf0a3da6ec Binary files /dev/null and b/doc/images/architecture/sdk/flows-capif_illustration.jpg differ diff --git a/doc/images/architecture/sdk/flows-data_schema.jpg b/doc/images/architecture/sdk/flows-data_schema.jpg new file mode 100644 index 0000000000000000000000000000000000000000..9cafb7c1e6aaa02e0ef089ca20d7efbf4b33f323 Binary files /dev/null and b/doc/images/architecture/sdk/flows-data_schema.jpg differ diff --git a/doc/images/architecture/sdk/flows-event_subscription.jpg b/doc/images/architecture/sdk/flows-event_subscription.jpg new file mode 100644 index 0000000000000000000000000000000000000000..e2315231bc3d0385c78146ba118d26e4d38426fd Binary files /dev/null and b/doc/images/architecture/sdk/flows-event_subscription.jpg differ diff --git a/doc/images/architecture/sdk/flows-invoker_check_authentication.jpg b/doc/images/architecture/sdk/flows-invoker_check_authentication.jpg new file mode 100644 index 0000000000000000000000000000000000000000..589a305a3c7a3909b32b1be60cc105000d0dc3d5 Binary files /dev/null and b/doc/images/architecture/sdk/flows-invoker_check_authentication.jpg differ diff --git a/doc/images/architecture/sdk/flows-invoker_discover.jpg b/doc/images/architecture/sdk/flows-invoker_discover.jpg new file mode 100644 index 0000000000000000000000000000000000000000..e51f04600fe2bd25686fb627c5084873b8c81fed Binary files /dev/null and b/doc/images/architecture/sdk/flows-invoker_discover.jpg differ diff --git a/doc/images/architecture/sdk/flows-invoker_get_tokens.jpg b/doc/images/architecture/sdk/flows-invoker_get_tokens.jpg new file mode 100644 index 0000000000000000000000000000000000000000..103966840ac019aed2cda9a4535a6b225e9bba37 Binary files /dev/null and b/doc/images/architecture/sdk/flows-invoker_get_tokens.jpg differ diff --git a/doc/images/architecture/sdk/flows-invoker_onboard.jpg b/doc/images/architecture/sdk/flows-invoker_onboard.jpg new file mode 100644 index 0000000000000000000000000000000000000000..a80a5ebdda7b539ddbbfedb5718feb064324bc74 Binary files /dev/null and b/doc/images/architecture/sdk/flows-invoker_onboard.jpg differ diff --git a/doc/images/architecture/sdk/flows-invoker_path.jpg b/doc/images/architecture/sdk/flows-invoker_path.jpg new file mode 100644 index 0000000000000000000000000000000000000000..6879f18f3ee43da6d9537d326e7885a2560e15c9 Binary files /dev/null and b/doc/images/architecture/sdk/flows-invoker_path.jpg differ diff --git a/doc/images/architecture/sdk/flows-invoker_update_offboard.jpg b/doc/images/architecture/sdk/flows-invoker_update_offboard.jpg new file mode 100644 index 0000000000000000000000000000000000000000..b1aef970f23cb65f82f24940dcaa16d2aa8533a2 Binary files /dev/null and b/doc/images/architecture/sdk/flows-invoker_update_offboard.jpg differ diff --git a/doc/images/architecture/sdk/flows-provider_logs.jpg b/doc/images/architecture/sdk/flows-provider_logs.jpg new file mode 100644 index 0000000000000000000000000000000000000000..f200d091af66958a0c5c6924cf4e28c64227c310 Binary files /dev/null and b/doc/images/architecture/sdk/flows-provider_logs.jpg differ diff --git a/doc/images/architecture/sdk/flows-provider_onboard.jpg b/doc/images/architecture/sdk/flows-provider_onboard.jpg new file mode 100644 index 0000000000000000000000000000000000000000..85c4662ba81fbbcaadbe5a66080a906a5d24819c Binary files /dev/null and b/doc/images/architecture/sdk/flows-provider_onboard.jpg differ diff --git a/doc/images/architecture/sdk/flows-provider_path.jpg b/doc/images/architecture/sdk/flows-provider_path.jpg new file mode 100644 index 0000000000000000000000000000000000000000..253b828ff2954e1bcee57e54c3e45571132554de Binary files /dev/null and b/doc/images/architecture/sdk/flows-provider_path.jpg differ diff --git a/doc/images/architecture/sdk/flows-provider_publish_functions.jpg b/doc/images/architecture/sdk/flows-provider_publish_functions.jpg new file mode 100644 index 0000000000000000000000000000000000000000..8104ee61855cd0a911cf47bff4af2c7b7e321b3a Binary files /dev/null and b/doc/images/architecture/sdk/flows-provider_publish_functions.jpg differ diff --git a/doc/images/architecture/sdk/flows-provider_update_offboard.jpg b/doc/images/architecture/sdk/flows-provider_update_offboard.jpg new file mode 100644 index 0000000000000000000000000000000000000000..4c8c4a3f9b16d5795e17f4cb29aaf0c367c18de3 Binary files /dev/null and b/doc/images/architecture/sdk/flows-provider_update_offboard.jpg differ diff --git a/doc/images/architecture/sdk/flows-sdk_with_register.jpg b/doc/images/architecture/sdk/flows-sdk_with_register.jpg new file mode 100644 index 0000000000000000000000000000000000000000..862a3533dd1b5114d0363c8480034dd0b2d0ed80 Binary files /dev/null and b/doc/images/architecture/sdk/flows-sdk_with_register.jpg differ diff --git a/doc/images/architecture/sdk/flows-updated_opencapif.jpg b/doc/images/architecture/sdk/flows-updated_opencapif.jpg new file mode 100644 index 0000000000000000000000000000000000000000..6e2ac44952889f949e79a62fca210d798ecfa57e Binary files /dev/null and b/doc/images/architecture/sdk/flows-updated_opencapif.jpg differ diff --git a/doc/sdk/sdk.md b/doc/sdk/sdk.md deleted file mode 100644 index d50d9fd48e84d0f368cd8ed090b08f6451ba8be6..0000000000000000000000000000000000000000 --- a/doc/sdk/sdk.md +++ /dev/null @@ -1,6 +0,0 @@ -# SDK - -Check [SDK repository](https://labs.etsi.org/rep/ocf/sdk) for further information. - -[OCF Web]: https://ocf.etsi.org/ "OCF Web" -[OCF Documentation]: https://ocf.etsi.org/documentation/ "OCF Documentation" diff --git a/doc/sdk/sdk_configuration.md b/doc/sdk/sdk_configuration.md new file mode 100644 index 0000000000000000000000000000000000000000..ff2b18e001c40ac29b7cae477870bf056e6599e7 --- /dev/null +++ b/doc/sdk/sdk_configuration.md @@ -0,0 +1,115 @@ +# OpenCAPIF SDK Configuration + +Before starting the configuration process, it is required that both the [requirements](./sdk_requirements.md) and the [installation](./sdk_developers.md) sections are completed. + +## Configuration via `capif_sdk_config.json` + +A sample configuration file can be found [here](https://labs.etsi.org/rep/ocf/sdk/-/blob/main/samples/config_sample.json). + +## Common Fields for Invoker and Provider + +Regardless of the role (Invoker or Provider), the following fields are mandatory: + +- `capif_host` +- `register_host` +- `capif_https_port` +- `capif_register_port` +- `capif_username` +- `capif_password` +- `debug_mode` + +### Network App Invoker + +When configuring the SDK as a **Network App Invoker**, the following fields must be provided: + +- `invoker_folder` +- `capif_callback_url` +- `supported_features` +- `cert_generation` (fields such as `csr_common_name`, `csr_country_name`, etc.) For csr_country_name it is important to fulfill the field with [THIS format](https://www.ssl.com/country-codes/) + +**Optional:** + +- `discover_filter`: useful to enable the discovery of specific APIs. Some fields under [`discover_filter`](#configuration-of-discover_filter) structure required to be configured when using discovery filters. Check devoted section below, +- `check_authentication_data`: useful to use `check_authentication()` function to validate features from a target provider, it will be required to fill up the `ip` and `port` parameters within the `check_authentication_data` variable. + +### Network App Provider + +For SDK configuration as a **Network App Provider**, the following fields are required: + +- `provider_folder` +- `supported_features` +- `cert_generation` (fields such as `csr_common_name`, `csr_country_name`, etc.) +- `APFs` +- `AEFs` +- [`publish_req`](#configuration-of-publish_req) +- `api_description_path` + +## Configuration of `discover_filter` + +The `discover_filter` section adheres to the parameters defined in the GET request schema of the [Discover Services API](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Discover_Service_API.yaml). + +To use the service discovery functionality, the `discover_filter` fields should be populated with the desired filters. **It is important to note that fields such as `api-name` must contain only one entry of each type (i.e., no lists are allowed in api-name).** + +For instance if the invoker fill the `api-name` field, the `discover()` functionality will retrieve only one API, the one that matches the exact name of the `api-name`. + +Before running the Invoker Service Discovery Functionality, the Invoker must be onboarded to CAPIF. + +## Configuration of `publish_req` + +This section is mandatory when using the [CAPIF Publish Service API](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Publish_Service_API.yaml). The following fields are required: + +- `service_api_id`: Example: `"02eff6e1b3a8f7c8044a92ee8a30bd"` +- `publisher_apf_id`: Example: `"APFa165364a379035d14311deadc04332"` +- `publisher_aefs_ids`: An array of selected AEF IDs. Example: `["AEFfa38f0e855bffb420e4994ecbc8fb9", "AEFe8bfa711f4f0c95ba0b382508e6382"]` + +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. + +To obtain this schema, opencapif_sdk has a facility to translate Openapi structures to ServiceAPIDescription schemas. +More information: [Translator functionality](./sdk_openapi_translation.md) + +If the `publisher_aefs_ids` do not match the `aefProfiles` in the API description, an error will be raised by the SDK. + +## Descriptions of `capif_sdk_config` fields + +This file can also be populated using [environment variables](https://labs.etsi.org/rep/ocf/sdk/-/blob/main/samples/enviroment_variables_sample.txt). + +- `invoker_folder`: The path (relative or absolute) where invoker information (certificates, keys, etc.) is stored. +- `provider_folder`: The path (relative or absolute) where provider information is stored. +- `supported_features`: A string used to indicate the features supported by an API, invoker or provider. The string shall contain a bitmask indicating supported features in hexadecimal representation Each character in the string shall take a value of "0" to "9", "a" to "f" or "A" to "F". [More information](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29571_CommonData.yaml) +- `capif_host`: The domain name of the CAPIF host. +- `register_host`: The domain name of the register host. +- `capif_https_port`: The CAPIF host port number. +- `capif_register_port`: The register host port number. +- `capif_callback_url`: The URL used by CAPIF to send invoker notifications (currently unavailable). +- `cert_generation`: Fields for certificate generation, with `csr_country_name` requiring a two-letter country code. +- `capif_username`: The CAPIF username. +- `capif_password`: The CAPIF password. +- `apfs`: The number of APFs to be onboarded as a provider (e.g., `5`). +- `aefs`: The number of AEFs to be onboarded as a provider (e.g., `2`). +- `debug_mode`: A boolean value to enable or disable SDK logs (e.g., `True` or `False`). +- [`discover_filter`](#configuration-of-discover_filter): Fields for configuring invoker service discovery. +- [`publish_req`](#configuration-of-publish_req): Fields required for API publishing. +- `api_description_path`: The path to the [ServiceAPIDescription](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Publish_Service_API.yaml) JSON file. +- `check_authentication_data`: The `ip` and `port` of the target Provider's AEF to get their supported features from. +- `log`: The structure defined in the [Log schema](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Logging_API_Invocation_API.yaml), it is not needed to fulfill the `apiId` field. +- `events`: The structure defined in the [EventSubscription schema](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Events_API.yaml), It is only necessary the `description` and `eventFilters` fields, in case of provider is also mandatory to fulfill `notificationDestination` and `websockNotifConfig` + + +## Configuration via `capif_sdk_register.json` + +To use this SDK in a local environment for creating and removing users, the following fields must be populated. Note that this feature is not included in the SDK, but instructions can be found in the [CAPIF official repository](https://labs.etsi.org/rep/ocf/capif/-/tree/REL1?ref_type=heads). + +- `register_host`: The domain name of the register host. +- `capif_register_port`: The port number of the register host. +- `capif_register_username`: The CAPIF admin username. +- `capif_register_password`: The CAPIF admin password. +- `capif_username`: The CAPIF user username. +- `capif_password`: The CAPIF user password. +- `config_path`: The absolute path to the configuration files folder. +- `uuid`: The UUID required for de-registering a user (only mandatory for de-registration). + +This file is used for the following functionalities: +- Register and login. +- Deregister and login. + +All fields are required except for `uuid`, which is only mandatory for de-registration. It is recommended to store the `uuid` returned from the registration process for future use. diff --git a/doc/sdk/sdk_developers.md b/doc/sdk/sdk_developers.md new file mode 100644 index 0000000000000000000000000000000000000000..ea925993692eb0620cf35f91728407c12e4ec432 --- /dev/null +++ b/doc/sdk/sdk_developers.md @@ -0,0 +1,81 @@ + +# OpenCAPIF SDK Development Environment Installation + +Before proceeding, ensure you have fulfilled the necessary [requirements](./sdk_requirements.md). + +Follow the steps below to install the OpenCAPIF SDK for development purposes: + +## Requisites + +Developers must have the following tools installed: + +- pyenv + +## Installation Steps + +### 1. Set Up a Python Environment with `pyenv` + +Follow these steps to create and activate a virtual environment using `pyenv`: + +```bash +# Install Python 3.12 using pyenv +pyenv install 3.12 + +# Create a virtual environment for the SDK +pyenv virtualenv 3.12 pesp_sdk_env + +# Activate the virtual environment +source path/to/.pyenv/versions/pesp_sdk_env/bin/activate +``` + +OPTIONAL step: sometimes Apple Mac shells raise issues while finding the shell path. If this happens, try this command: + +```console +export PATH="$HOME/.pyenv/bin:$PATH" +eval "$(pyenv init --path)" +eval "$(pyenv init -)" +eval "$(pyenv virtualenv-init -)" +``` +OPTIONAL step: For Arm64 architecture sometimes will appear this problem + +```console +Last 10 log lines: + __locale_localeconv in _localemodule.o + __locale_localeconv in _localemodule.o + __locale_localeconv in _localemodule.o + __locale_localeconv in _localemodule.o +"_libintl_textdomain", referenced from: + __locale_textdomain in _localemodule.o +ld: symbol(s) not found for architecture arm64 +clang: error: linker command failed with exit code 1 (use -v to see invocation) +make: *** [Programs/_freeze_module] Error 1 +make: *** Waiting for unfinished jobs.... +``` + + +This [article](https://laict.medium.com/install-python-on-macos-11-m1-apple-silicon-using-pyenv-12e0729427a9) explains how to solve it + + +### 2. Clone GitHub repository: + +```console +git clone https://labs.etsi.org/rep/ocf/sdk.git +``` + +```console +#Then move to the pesp_capif_sdk folder + +cd /the/path/to/pesp_capif_sdk +``` + +### 3. Install the Python requirements listed in [requirements.txt](https://labs.etsi.org/rep/ocf/sdk/-/blob/main/installation/requirements.txt) file: + +```console +cd installation + +python -m pip install --upgrade pip + +pip install -r requirements.txt +``` + +**Congratulations!** The installation of OpenCAPIF SDK has finished. \ No newline at end of file diff --git a/doc/sdk/sdk_full_documentation.md b/doc/sdk/sdk_full_documentation.md new file mode 100644 index 0000000000000000000000000000000000000000..3a1c36179487b34f262141efc1b4ef685e6a9325 --- /dev/null +++ b/doc/sdk/sdk_full_documentation.md @@ -0,0 +1,364 @@ + +# OpenCAPIF SDK full documentation + +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. + +## Getting Started + +Before using the SDK, the following steps should be completed: + +- Meet the [requirements](./sdk_requirements.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. + +## Available SDK Usage Modes + +![GENERAL CAPIF USAGE FLOW](../images/architecture/sdk/flows-updated_opencapif.jpg) + +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](https://labs.etsi.org/rep/ocf/sdk/-/tree/main/network_app_samples) folder. + +2. **Manual Mode**: A set of Python [scripts](https://labs.etsi.org/rep/ocf/sdk/-/tree/main/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`. + +## Provider Network App + +The OpenCAPIF SDK enables efficient implementation of invoker functionality for Network App. This section details the SDK features related to CAPIF providers. + +### Important Information for 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__.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(supp_features)` +- **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`. +`supp_features` parameter is optional and it stands for communicating to the CCF the supported features. Its default value it's `0`. + +![Provider_onboard](../images/architecture/sdk/flows-provider_onboard.jpg) + +### 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__.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](./sdk_openapi_translation.md) + +**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 + +### Service Deletion + +OpenCAPIF SDK references: + +- **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 +- service_api_id + +### Service Update + +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. + +**Required SDK inputs**: + +- 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. + +**Required SDK inputs**: + +- service_api_id +- publisher_apf_id + +### Get All Services + +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](#service-publishing). + +**Required SDK input**: + +- publisher_apf_id + +![Provider_publish](../images/architecture/sdk/flows-provider_publish_functions.jpg) + +### Update and Offboard Provider + +OpenCAPIF SDK references: + +- **Functions**: `update_provider(supp_features)` and `offboard_provider()` +- **Scripts**: `provider_capif_connector_update.py` and `provider_capif_connector_offboarding.py` + +`update_provider(supp_features)`: 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. + +`supp_features` parameter is optional and it stands for communicating to the CCF the supported features. Its default value it's `0`. + +The provider must be onboarded before using these features. + +![Provider_update-offboard](../images/architecture/sdk/flows-provider_update_offboard.jpg) + +### Create logs + +OpenCAPIF SDK references: + +- **Function**: `create_logs(aefId, jwt, supp_features)` + +The provider notifies to the CCF that the published API has been used by certain invoker. + +`supp_features` parameter is optional and it stands for communicating to the CCF the supported features. Its default value it's `0`. + +For leveraging this feature the Provider must have onboarded and published an API previously. + +**Required SDK input**: + +- aefId (Within the function) +- jwt (Within the function) +- log (Within [SDK configuration](./sdk_configuration.md) or object) + +![Provider_logs](../images/architecture/sdk/flows-provider_logs.jpg) + +### Create subscription + +OpenCAPIF SDK references: + +- **Function**: `create_subscription(name, id, supp_features)` + +The provider ask to the CCF about notifications related to services such as SERVICE_API_AVAILABLE or API_INVOKER_UPDATED. + +`supp_features` parameter is optional and it stands for communicating to the CCF the supported features. Its default value it's `0`. + +This services are specificated in [CAPIF Events API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Events_API.yaml) explained in [SDK configuration](./sdk_configuration.md#descriptions-of-capif_sdk_config-fields) + +For leveraging this feature the Provider must have onboarded previously. + +**Required SDK input**: + +- aefId//apfId//amfId (Within the function) +- name: An arbitrary name we want to set in order to store it. +- events (Within [SDK configuration](./sdk_configuration.md#descriptions-of-capif_sdk_config-fields) or object) + +### Delete subscription + +OpenCAPIF SDK references: + +- **Function**: `delete_subscription(name, id)` + +The provider ask to the CCF to withdraw the subscription to the notifications asked previously + +For leveraging this feature the Provider must have onboarded and created a subscription previously. + +**Required SDK input**: + +- aefId//apfId//amfId (Within the function) +- name: The name of your subscription. + +### Update subscription + +OpenCAPIF SDK references: + +- **Function**: `update_subscription(name, id, supp_features)` + +The provider ask to the CCF about updating the subscription for receiving different services such as SERVICE_API_AVAILABLE or API_INVOKER_UPDATED, changing the URL for receiving the notifications... + +This services are specificated in [CAPIF Events API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Events_API.yaml) explained in [SDK configuration](./sdk_configuration.md#descriptions-of-capif_sdk_config-fields) + +`supp_features` parameter is optional and it stands for communicating to the CCF the supported features. Its default value it's `0`. + +For leveraging this feature the Provider must have onboarded and created a subscription previously. + +![Events_feature](../images/architecture/sdk/flows-event_subscription.jpg) + +**ONLY AVAILABLE IN CAPIF RELEASE 2** + +**Required SDK input**: + +- aefId//apfId//amfId (Within the function) +- name: The name of your subscription. +- events (Within [SDK configuration](./sdk_configuration.md#descriptions-of-capif_sdk_config-fields) or object) + +### Patch subscription + +OpenCAPIF SDK references: + +- **Function**: `update_subscription(name, id)` + +The provider ask to the CCF about updating the subscription for receiving different services such as SERVICE_API_AVAILABLE or API_INVOKER_UPDATED. + +`supp_features` parameter is optional and it stands for communicating to the CCF the supported features. Its default value it's `0`. + +This services are specificated in [CAPIF Events API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Events_API.yaml) explained in [SDK configuration](./sdk_configuration.md#descriptions-of-capif_sdk_config-fields) + +For leveraging this feature the Provider must have onboarded and created a subscription previously. + +**ONLY AVAILABLE IN CAPIF RELEASE 2** + +**Required SDK input**: + +- aefId//apfId//amfId (Within the function) +- name: The name of your subscription. +- events (Within [SDK configuration](./sdk_configuration.md#descriptions-of-capif_sdk_config-fields) or object) + + +## Invoker Network App + +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. + +### Invoker onboarding + +OpenCAPIF SDK references: + +- **Function**: `onboard_invoker(supp_features)` +- **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`. + +`supp_features` parameter is optional and it stands for communicating to the CCF the supported features. Its default value it's `0`. + + +![Invoker_onboard](../images/architecture/sdk/flows-invoker_onboard.jpg) + +### 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. + +![Invoker_discover](../images/architecture/sdk/flows-invoker_discover.jpg) + +### Obtain JWT Tokens + +OpenCAPIF SDK references: + +- **Function**: `get_tokens(supp_features)` +- **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`. +`supp_features` parameter is optional and it stands for retrieve the token of the services that have certain supported features. Its default value it's `0`. + +![Invoker_get_token](../images/architecture/sdk/flows-invoker_get_tokens.jpg) + +### Check authentication + +OpenCAPIF SDK references: + +- **Function**: `check_authentication(supported_features)` + +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. + +**Required SDK inputs**: + +- check_authentication_data + +![Invoker_check_authentication](../images/architecture/sdk/flows-invoker_check_authentication.jpg) + +### Update and Offboard Invoker + +OpenCAPIF SDK references: + +- **Functions**: `update_invoker(supp_features)` and `offboard_invoker()` +- **Scripts**: `invoker_capif_connector_update.py` and `invoker_capif_connector_offboarding.py` + +Onboarding is required before utilizing these functions. + +`supp_features` parameter is optional and it stands for communicating to the CCF the supported features. Its default value it's `0`. + + +![Invoker_update-offboard](../images/architecture/sdk/flows-invoker_update_offboard.jpg) + +## Additional Features + +### CAPIF Registration and Login + +OpenCAPIF SDK reference: + +- **Script**: `register_and_login.py` + +Simplifies the login process for admin users and creates a CAPIF user. + +### CAPIF Deregistration and Logout + +OpenCAPIF SDK reference: + +- **Script**: `deregister_and_login.py` + +Simplifies the logout process for admin users and removes a CAPIF user. + +![Register picture](../images/architecture/sdk/flows-sdk_with_register.jpg) diff --git a/doc/sdk/sdk_introduction.md b/doc/sdk/sdk_introduction.md new file mode 100644 index 0000000000000000000000000000000000000000..5089e0fc3a195025df88076c23babcf10e686d8c --- /dev/null +++ b/doc/sdk/sdk_introduction.md @@ -0,0 +1,16 @@ +# OpenCAPIF SDK Introduction +[![PyPI version](https://img.shields.io/pypi/v/opencapif-sdk.svg)](https://pypi.org/project/opencapif-sdk/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![Python](https://img.shields.io/badge/python-v3.12+-blue.svg) [![PyPI - Downloads](https://img.shields.io/pypi/dm/opencapif-sdk)](https://pypi.org/project/opencapif-sdk/) + +![OpenCAPIF icon](../images/logos/OpenCAPIF.webp) + +This documentation is related to the OpenCAPIF SDK, which is a Software Development Kit that is intended to help on developing Network Applications (NA) or services based on OpenCAPIF. + +OpenCAPIF SDK provides a set of libraries that enable either CAPIF provider or invoker roles, as other functionality that simplify reaching OpenCAPIF API. + +Current version of OpenCAPIF SDK is compatible with following publicly available releases: + +- [OpenCAPIF Release 3.0](../releasenotes.md#release-300) +- [OpenCAPIF Release 2.0](../releasenotes.md#release-200) +- [OpenCAPIF Release 1.0](../releasenotes.md#release-100) + +This document serves as the [main reference](./sdk_requirements.md#network-app-developer-path) to start working with OpenCAPIF SDK. For advanced users, refer to [OpenCAPIF full documentation](./sdk_full_documentation.md) section to dig into all available features. \ No newline at end of file diff --git a/doc/sdk/sdk_known_issues.md b/doc/sdk/sdk_known_issues.md new file mode 100644 index 0000000000000000000000000000000000000000..b2da12987c4cbf8dbb3bcab67e16105f60699c46 --- /dev/null +++ b/doc/sdk/sdk_known_issues.md @@ -0,0 +1,12 @@ +# OpenCAPIF SDK known issues + +There are some features which **are not currently available at latest OpenCAPIF SDK release**. Those are assumed to be technical debt and might be available in future releases: + + - [CAPIF Access control policy management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Access_Control_Policy_API.yaml) + - [CAPIF Auditing API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Auditing_API.yaml) + - [CAPIF Routing info API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Routing_Info_API.yaml) + - [CAPIF Security API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Security_API.yaml) + - /trustedInvokers/{apiInvokerId}/delete (POST) + - /trustedInvokers/{apiInvokerId} (GET) + - /trustedInvokers/{apiInvokerId} (DELETE) + - Nontype Error: When using SDK as a Provider, if the user does update the provider to more AEFs/APFs than previously, the SDK has an error using the publish functionality diff --git a/doc/sdk/sdk_openapi_translation.md b/doc/sdk/sdk_openapi_translation.md new file mode 100644 index 0000000000000000000000000000000000000000..25a745ffd75e619df64b1f97aa745e9ae9fc38ce --- /dev/null +++ b/doc/sdk/sdk_openapi_translation.md @@ -0,0 +1,15 @@ +# 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("https://192.168.1.10:8080/exampleAPI/v1", "0", "0") +``` + +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. +The supported_features and api_supp_features fields corresponds to the capabilities of the provider and the service that the user is sharing. diff --git a/doc/sdk/sdk_requirements.md b/doc/sdk/sdk_requirements.md new file mode 100644 index 0000000000000000000000000000000000000000..8af94622400d5ecdf4334d02cc15d2506b2d49a6 --- /dev/null +++ b/doc/sdk/sdk_requirements.md @@ -0,0 +1,374 @@ +# OpenCAPIF SDK + +## Network App developers + +In the scope of CAPIF, a Network App (Network Application) refers to an external application or service that interacts with the 3GPP network via standardized APIs. These Network Apps typically leverage the capabilities and services provided by the underlying mobile network infrastructure, such as network slicing, quality of service (QoS), or location services. + +Network Apps can be developed by third-party service providers, network operators, or other stakeholders to offer a wide range of services, including enhanced communication features, IoT solutions, or content delivery, and they use CAPIF as the unified framework for securely discovering, accessing, and utilizing 3GPP network APIs. + +Next image illustrates how CAPIF works and where the SDK provides means to integrate with it: + +![CAPIF-illustration](../images/architecture/sdk/flows-capif_illustration.jpg) + +For that purpose Network Apps play 2 different roles when interacting with CAPIF: +- **Invoker**: a Network App acting as an Invoker is responsible for consuming APIs exposed by other services. This role represents an external application or service that calls the 3GPP northbound APIs to utilize the network’s functionalities. + +- **Provider**: a Network App acting as a Provider is responsible for exposing its own APIs/services for use by Invokers. This role represents an entity that offers services through APIs, making them available to other external applications or Invokers.A provider also is distinguished for having three parts. + + - The **AMF (API Management Function)**, supplies the API provider domain with administrative capabilities. Some of these capabilities include, auditing the service API invocation logs received from the CCF, on-boarding/off-boarding new API invokers and monitoring the status of the service APIs.One provider can have only one AMF. + + - The **APF (API Publishing Function)**, is responsible for the publication of the service APIs to CCF in order to enable the discovery capability to the API Invokers.One provider can have multiple APFs. + + - The **AEF (API Exposing Function)**, is responsible for the exposure of the service APIs. Assuming that API Invokers are authorized by the CCF, AEF validates the authorization and subsequently provides the direct communication entry points to the service APIs. AEF may also authorize API invokers and record the invocations in log files.One provider can have multiple AEFs + +OpenCAPIF SDK brings a set of functions to integrate with the 5G Core's function CAPIF, as defined in [3GPP Technical Specification (TS) 29.222 V18.5.0 Common API Framework for 3GPP Northbound APIs](https://www.etsi.org/deliver/etsi_ts/129200_129299/129222/18.05.00_60/ts_129222v180500p.pdf). This section shows the mapping between the Python functions available in this SDK and the CAPIF OpenAPI APIs defined the reference standard: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
3GPP CAPIF APIOpenCAPIF SDK functionDescription
/onboardedInvokers (POST)onboard_invoker(supp_features)Registers a new invoker.
/onboardedInvokers/{onboardingId} (PUT)update_invoker(supp_features)Updates an existing invoker for a specific onboardingId.
/onboardedInvokers/{onboardingId} (DELETE)offboard_invoker()Deletes an invoker for a specific onboardingId.
registrations (POST)onboard_provider(supp_features)Registers a new service provider.
/registrations/{registrationId} (PUT)update_provider(supp_features)Updates a service provider's registration for a specific registrationId.
/registrations/{registrationId} (DELETE)offboard_provider()Deletes a service provider's registration for a specific registrationId.
/allServiceAPIs (GET)discover()Retrieves a list of all available service APIs.
/trustedInvokers (PUT//POST)get_tokens(supp_features)Registers or updates trusted invokers.
/securities/{securityId}/token (GET)get_tokens(supp_features)Retrieves a security token for a specific securityId. This JWT token is used to query the targeted services.
/{apfId}/service-apis(POST)publish_services()Registers a new service API into the system for a specific apfId
/{apfId}/service-apis/{serviceApiId} (DELETE)unpublish_service()Deletes a service API from the system for a specific apfIdand serviceApiId
/{apfId}/service-apis/{serviceApiId} (PUT)update_service()Updates the details of an existing service API for a specific apfIdand serviceApiId
/{apfId}/service-apis/{serviceApiId} (GET)get_service()Retrieves the details of a specific service API for a specific apfId and serviceApiId
/{apfId}/service-apis (GET)get_all_services()Retrieves a list of all available service APIs for a specific apfId
/aef-security/v1/check-authentication (POST)check_authentication(supported_features)This custom operation allows the API invoker to confirm the supported_features from the API exposing function(AEF)
/api-invocation-logs/v1/{aefId}/logs (POST)create_logs(aefId, jwt,supp_features)This operation allows to the Provider to notice to the CCF about the query of an invoker with the JWT token recieved
/capif-events/v1/{subscriberId}/subscriptions (POST)create_subscription(name, id, supp_features)This operation allows to the Invoker/AEF/APF/AMF to ask to the CCF about notifications related to certain functionalities.
/capif-events/v1/{subscriberId}/subscriptions/{subscriptionId} (DELETE)delete_subscription(name, id)This operation allows to the Invoker/AEF/APF/AMF to withdraw the petition to receive notifications related to certain functionalities.
/capif-events/v1/{subscriberId}/subscriptions/{subscriptionId} (PUT)update_subscription(name, id, supp_features)This operation allows to the Invoker/AEF/APF/AMF to modify to the petition to receive notifications related to certain functionalities. ONLY AVAILABLE IN OPENCAPIF RELEASE 2
/capif-events/v1/{subscriberId}/subscriptions/{subscriptionId} (PATCH)patch_subscription(name, id, supp_features)This operation allows to the Invoker/AEF/APF/AMF to modify to the petition to receive notifications related to certain functionalities. ONLY AVAILABLE IN OPENCAPIF RELEASE 2
+ +NOTE: Above mentioned CAPIF APIs are defined in these 3GPP references: + +- [CAPIF Invoker API specification](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_API_Invoker_Management_API.yaml) +- [CAPIF Provider API specification](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_API_Provider_Management_API.yaml) +- [CAPIF Discover API specification](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Discover_Service_API.yaml) +- [CAPIF Publish API specification](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Publish_Service_API.yaml) +- [CAPIF Security API specification](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Security_API.yaml) +- [AEF Security API specification](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_AEF_Security_API.yaml) +- [CAPIF Logging API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Logging_API_Invocation_API.yaml) +- [CAPIF Events API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Events_API.yaml) + +NOTE: In the [3GPP Technical Specification (TS) 29.222 V18.5.0 Common API Framework for 3GPP Northbound APIs](https://www.etsi.org/deliver/etsi_ts/129200_129299/129222/18.05.00_60/ts_129222v180500p.pdf) the `service` concept is understood as equal as the `API` concept. + + +## OpenCAPIF SDK requirements + +To use the OpenCAPIF SDK, a registered user account within the target CAPIF instance is required. + +**Contact the administrator to obtain the required predefined credentials (CAPIF username and password).** + +## OpenCAPIF SDK installation + +To install the OpenCAPIF SDK source code for developing purposes there is an available section: [OpenCAPIF SDK developers](./sdk_developers.md). + +To use the SDK, binary installer for the latest version is available at the [Python Package Index (Pipy)](https://pypi.org/project/opencapif-sdk/) + +The SDK works with **Python 3.12** + +```console +pip install opencapif_sdk +``` + +## OpenCAPIF SDK Data Schema + +Here is a visual look on the variables of the CAPIF sdk referenced in: + +- [Important information for Invoker Consumer](#important-information-for-invoker-consumer) +- [Important information for Provider Consumer](#important-information-for-provider-consumers) + +![sdk_data_schema](../images/architecture/sdk/flows-data_schema.jpg) + +## Network App developer path + +The Network App Developer Path guides the programmer through building and integrating Network Apps using CAPIF. This path is divided into two key sections: [Invoker Network App](#invoker-network-app) and [Provider Network App](#provider-network-app). Each section covers the essential flow and functions for developing Network Apps interaction with CAPIF, whether the user is acting as an invoker consuming services or a provider offering them. By following this path, developers will gain a comprehensive understanding of how to effectively use the SDK within the CAPIF ecosystem. + +Here is a good explanation about how a usual flow of a Network App should work: [usual flow example](https://ocf.etsi.org/documentation/latest/testing/postman/) + +## Provider Network App + +A Network App development running as a Provider would typically follow this process step by step, making use of the SDK: + +![PROVIDER_PATH](../images/architecture/sdk/flows-provider_path.jpg) + +Now, it is described in 4 simple steps how a Provider can be developed in just some code lines, below snippet. It describes the usual flow a Provider would follow to publish an API service. + +```python + import opencapif_sdk + + provider = opencapif_sdk.capif_provider_connector(config_file="path/to/capif_sdk_config.json") + provider.onboard_provider() + + #translator = opencapif_sdk.api_schema_translator("./path/to/openapi.yaml") + #translator.build("https://192.168.1.10:8080/exampleAPI/v1", "0", "0") + + provider.api_description_path = "./api_description_name.json" + + APF = provider.provider_capif_ids["APF-1"] + + AEF1 = provider.provider_capif_ids["AEF-1"] + AEF2 = provider.provider_capif_ids["AEF-2"] + + provider.publish_req['publisher_apf_id'] = APF + provider.publish_req['publisher_aefs_ids'] = [AEF1, AEF2] + provider.supported_features ="4" + provider.publish_services() +``` + +Code is next explained step by step: + +1. **Create a Provider object:** + Initialize the provider by creating an instance of the `capif_provider_connector` class, passing the required [configuration](./sdk_configuration.md) file. + + Make sure that the configuration file is filled before creating the instance. + + +2. **Onboard the Provider:** + Register the provider with the CAPIF system to enable the publication of APIs: + + In this phase, the SDK creates and stores all the necessary files for using CAPIF as a provider, such as the authorization certificate, the server certificate and each of the APFs and AEFs certificates .Furthermore creates a file named `provider_capif_ids.json`, which stores important information about the provider. + +3. **Prepare API details:** + In the `provider_folder`, more specifically in the `capif_username` folder, it will be sotres the provider API details file. This file contains all the APFs and AEFs IDs that have already onboarded with this `capif_username`. + + 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.** + + If the **API** is defined in an Openapi.yaml format, the sdk has a facility which creates automatically the **API schema description**.For using this functionality uncomment the translator lines. More information: [Translator functionality](./sdk_openapi_translation.md) + + Choose one APF and the AEF identifiers, and fulfill the `publish_req` structure and the `api_description_path`. + + The `provider_capif_ids` variable is a dictionary which contains key-values of all the APFs and AEFs stored as name: ID. + + This `publish_req` field can also be filled with object variables already stored at provider object. + +4. **Publish the services:** + Use the `publish_services()` method to register the APIs with the CAPIF framework. In this phase, the SDK does the publishing of the provided API specification. + + **At the end of this step, the API will be available for Invokers to be consumed.** + +Now, Provider Network App is ready to receive requests from Invokers. + +### Provider Network App sample + +This repository provides an implementation sample of a [Provider-Network App](https://labs.etsi.org/rep/ocf/sdk/-/blob/main/network_app_samples/network_app_provider_sample/network_app_provider.py). + +In this sample, the provider publishes two APIs and starts running the servers of each API on local environment. + +### Important information for Provider consumers + +Within the `provider_folder`, the SDK stores the created folders named with prefix of the provided `capif_username` that has been registered from administrator. At each folder, there will be found the following files: + +- `provider_capif_ids.json`: contains all the APFs and AEFs ids that have already onboarded with this `capif_username`, +- `capif__.json`: if it is already published or updated an API, it will contain a copy of the last payload, +- `service_received.json`: if it is already used to get an API or get all APIs functionality, it will contain the response of last request, +- `provider_service_ids.json`: contains the currently published APIs with their `api_id`. + +All the configuration values are available within the object `capif_provider_connector`. + +The `provider_service_ids` variable stores the `provider_service_ids.json` content in a dictionary form. + +The `provider_capif_ids` variable stores the `provider_capif_ids.json` content in a dictionary form. + + +## Invoker Network App + +A Network App development running as an Invoker would typically follow this process step by step, making use of the SDK: + +![INVOKER_PATH](../images/architecture/sdk/flows-invoker_path.jpg) + +Now, it is described in some simple steps how an Invoker can be developed in just some code lines. Find below the code snippet. It describes the usual flow an Invoker would follow to consume APIs from CAPIF. + +```python + import opencapif_sdk + + invoker = opencapif_sdk.capif_invoker_connector(config_file="path/to/the/capif_sdk_config.json") + invoker.onboard_invoker() + service_discoverer = opencapif_sdk.service_discoverer(config_file="path/to/the/capif_sdk_config.json") + service_discoverer.discover() + service_discoverer.get_tokens() + jwt_token=service_discoverer.token +``` + +Code is next explained step by step: + +1. **Create an Invoker object:** + Initialize the invoker by creating an instance of the `capif_invoker_connector` class, passing the required [configuration](./sdk_configuration.md) file. + + Make sure that the configuration file is filled out before creating the instance. + +2. **Onboard the Invoker**: + Register the target invoker with the CAPIF system to enable access to APIs. + + In this phase, the SDK creates and stores all the necessary files for using CAPIF as a invoker, such as the authorization certificate and the server certificate.Furthermore,it creates a file named `capif_api_security_context_details.json` , which stores important information about the invoker. + +3. **Create a Service Discoverer object:** + Initialize the service discovery mechanism to search for available services(APIs) in CAPIF. + +4. **Discover available services:** + Use the `discover()` method to retrieve a list of available APIs. In this phase, the SDK finds all the available APIs for the invoker. Consequently, it saves the most important information and stores it within the `capif_api_security_context_details.json`. + + **DISCLAIMER:** If it is the first time the user runs `discover()`, it will show a warning alert like following: + + WARNING - Received 404 error, redirecting to register security service + + This alert is expected because the SDK tries to update the security context first. If a 404 error is received, it means the security context is not created yet, so the next step for the SDK is to register a new security service. + +5. **Retrieve security tokens:** + Use the `get_tokens()` method to obtain the necessary tokens for authenticating API requests. + +**At the end of this flow, the invoker has been onboarded and it is ready to use target APIs.** All required information, including the access_token to use the available APIs, is stored at `capif_api_security_context_details.json` file. This file is placed in the invoker_folder path, specifically in the folder that corresponds to the capif_username used in the `capif_sdk_config.json`. A sample of the [capif_api_security_context_details](https://labs.etsi.org/rep/ocf/sdk/-/blob/main/samples/capif_api_security_context_details_sample.json) is also available. + +Now, Invoker Network App can use access tokens to consume real services. + +### Invoker Network App sample + +Here is a code sample of the implementation of an [Invoker-Network App](https://labs.etsi.org/rep/ocf/sdk/-/blob/main/network_app_samples/network_app_invoker_sample/network_app_invoker.py). + +In this sample, the invoker will discover the APIs published by the sample provider shown in this document and will return the access token for querying the APIs. This sample is prepared to run after the [Provider-Network App](https://labs.etsi.org/rep/ocf/sdk/-/blob/main/network_app_samples/network_app_provider_sample/network_app_provider.py). + +Make sure that the [Provider-Network App](https://labs.etsi.org/rep/ocf/sdk/-/blob/main/network_app_samples/network_app_provider_sample/network_app_provider.py) is running before following this implementation. + +For testing APIs availability, after running both samples([Provider-Network App](https://labs.etsi.org/rep/ocf/sdk/-/blob/main/network_app_samples/network_app_provider_sample/network_app_provider.py) and [Invoker-Network App](https://labs.etsi.org/rep/ocf/sdk/-/blob/main/network_app_samples/network_app_invoker_sample/network_app_invoker.py)) the invoker app will return the access token. + +Also, in the same Invoker-Network folder is available a [Postman collection and environment](https://labs.etsi.org/rep/ocf/sdk/-/tree/main/network_app_samples/network_app_invoker_sample/postman). In order to test these APIs, the access token returned in the Invoker-Network App must be set in the Postman environment, more specifically in the `access_token` variable. + +Another alternative is to import the [Postman collection and environment](https://labs.etsi.org/rep/ocf/sdk/-/tree/main/network_app_samples/network_app_invoker_sample/postman) in your own postman account and fill the `postman_api_key` and the `environment_id` fields within the [Invoker-Network App](https://labs.etsi.org/rep/ocf/sdk/-/blob/main/network_app_samples/network_app_invoker_sample/network_app_invoker.py). Here is an example of these two fields that need to be fulfilled. + +```python + # Your Postman API Key + postman_api_key = "AAAA-your-apikey" + + # Postman Environment ID + environment_id = "your-environment-id-must-be-here" +``` + +### Important information for Invoker consumer + +In the `invoker_folder`, it will be located several folders with each `capif_username` it has been onboarded as a provider. For each folder, it will be found: + +- `capif_api_security_context_details.json`: This file contains the information of the invoker. It will contain: + + 1. The `api_invoker_id`, + 2. If the Service Discovery Functionality has already been used , it will be found all the available APIs with their information, + 3. If the Service Get Token functionality has already been used , it will be found the access token for using the APIs that has already been discovered. + +The `token` variable is also available for retrieving the JWT token after the `get_tokens()` method. + +The `invoker_capif_details` variable stores the `capif_api_security_context_details.json` content in a dictionary form. diff --git a/mkdocs.yml b/mkdocs.yml index 22ebe4a2d703cdacf676defa2e3b67c40e04257f..49a9e82848f1155367fcada4e7c36fa3ece43291 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -98,7 +98,13 @@ nav: - Dynamic Configuration: ./configuration/configuration.md - Event Reporting Information: ./event-req/event-req.md - SDK: - - Introduction: ./sdk/sdk.md + - Introduction: ./sdk/sdk_introduction.md + - Requirements: ./sdk/sdk_requirements.md + - Configuration: ./sdk/sdk_configuration.md + - Developers Guide: ./sdk/sdk_developers.md + - Full Documentation: ./sdk/sdk_full_documentation.md + - OpenAPI Translation: ./sdk/sdk_openapi_translation.md + - Known Issues: ./sdk/sdk_known_issues.md - Example Clients: - Introduction: ./example-clients/example-clients.md - Testing: