Improve data structure (#4)

  - 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

**Network Apps developers are the target users of OpenCAPIF SDK.**

## OpenCAPIF SDK summary

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 API**                                    | **OpenCAPIF SDK function**                                  | **Description**                                             |

| /{apfId}/service-apis/{serviceApiId} (PUT)            | [update_service()](./doc/sdk_full_documentation.md#services-update)                                            | Updates the details of an existing service API for a specific `apfId`and `serviceApiId`             |

| /{apfId}/service-apis/{serviceApiId} (GET)                           | [get_service()](./doc/sdk_full_documentation.md#get-services)                                               | Retrieves the details of a specific service API for a specific `apfId` and `serviceApiId`           |

| /{apfId}/service-apis (GET)            | [get_all_services()](./doc/sdk_full_documentation.md#get-all-services)                                          | Retrieves a list of all available service APIs for a specific `apfId`            |

| /aef-security/v1/check-authentication (POST)            | [check_authentication()](./doc/sdk_full_documentation.md#check_authentication)                                          | This custom operation allows the API invoker to confirm the `supported_features` from the API exposing function(AEF)            |

NOTE: Above mentioned CAPIF APIs are defined in these 3GPP references:

- [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)

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.

**Contact the administrator to obtain the required predefined credentials (CAPIF username and password).**

## 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](./doc/images/flows_data_schema.png)

# 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.

  provider.onboard_provider()

  provider.api_description_path = "./nef_upf_vendor_1.json"

  APF = provider.api_prov_funcs["APF-1"]

  APF = provider.provider_capif_ids["APF-1"]

  AEF1 = provider.api_prov_funcs["AEF-1"]

  AEF2 = provider.api_prov_funcs["AEF-2"]

  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]

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 `capif_provider_details.json`, which stores important information about the provider.

    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 located the provider API details file.\

    This file contains all the APFs and AEFs ids that have already onboarded with this `capif_username`.\

    Also it is very important to have previously prepared the API description of the API is going to be published.\

    This file needs to follow the [CAPIF_Publish_Service_API](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Publish_Service_API.yaml).

    Choose one APF and the AEFs identifiers, and fulfill the   publish_req structure and the api_description_path:

    <p align="center">

      <img src="./doc/images/capif_provider_details_example.png" alt="example" width="400"/>

      <img src="./doc/images/publish_req_example.png" alt="config-example"  width="400"/>

    </p>

    Choose one APF and the AEFs identifiers, and fulfill the publish_req structure and the api_description_path.

    The api_prov_funcs variable is a dictionary which contains key-values of all the APFs and AEFs stored as name: ID.

    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.

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:

- `capif_provider_details.json`: contains all the APFs and AEFs ids that have already onboarded with this `capif_username`,

- `provider_capif_ids.json`: contains all the APFs and AEFs ids that have already onboarded with this `capif_username`,

- `capif_<api_name>_<api_id>.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,

- `published_apis.json`: contains the currently published APIs with their `api_id`.

- `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 api_prov_funcs variable stores the `capif_provider_details.json` content in a dictionary form.

The published_apis variable stores the `published_apis.json` content in a dictionary form.

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

The `token` variable is also available for retrieving the JWT token after the get_tokens() method.

The capif_api_details variable stores the `capif_api_security_context_details.json` content in a dictionary form.

The invoker_capif_details variable stores the `capif_api_security_context_details.json` content in a dictionary form.

# OpenCAPIF SDK known issues

      "service-kpis": ""

    }

  },

  "provider": {

    "provider_folder": "",

    "apfs": "",

- `invoker_folder`

- `capif_callback_url`

- `supported_features`

- `cert_generation` (fields such as `csr_common_name`, `csr_country_name`, etc.)

**Optional:**

To enable the discovery of specific APIs, the fields under [`discover_filter`](#configuration-of-discover_filter) can be configured.

To use `check_authentication()` it is required to fill the `ip` and `port` variables within the `check_authentication` variable

### Network App Provider

For SDK configuration as a **Network App Provider**, the following fields are required:

- [`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`: The `ip` and `port` of the target Provider's AEF to get their supported features from.

## Configuration via `capif_sdk_register.json`

- `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 deregistering a user (only mandatory for deregistration).

- `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 deregistration. It is recommended to store the `uuid` returned from the registration process for future use.

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.

- [Provider Network App](#provider-network-app)

    - [Important Information for Providers](#important-information-for-providers)

    - [Provider Onboarding](#provider-onboarding)

    - [Service Publishing](#services-publishing)

    - [Service Deletion](#services-deletion)

    - [Service Updates](#services-update)

    - [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)

- [Invoker Network App](#invoker-network-app)

    - [Important Information for Invokers](#important-information-for-invokers)

    - [Invoker Onboarding](#invoker-onboarding)

    - [Service Discovery](#discover-process)

    - [Obtain JWT Tokens](#obtain-invoker-tokens)

    - [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)

    - [CAPIF Registration and Login](#capif-registration-and-login)

## Provider Network App

The OpenCAPIF SDK allows the provider flow for Network-App to be implemented with minimal code. This section provides a comprehensive overview of the SDK features relevant to CAPIF providers.

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:

- `capif_provider_details.json`: Contains all APFs and AEFs IDs onboarded with the associated username.

- `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.

- `published_apis.json`: A list of currently published APIs along with their IDs.

- `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 api_prov_funcs variable stores the `capif_provider_details.json` content in a dictionary form.

The published_apis variable stores the `published_apis.json` content in a dictionary form.

The provider_capif_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.

### Provider Onboarding

- **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 `capif_provider_details.json`.

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`.

![Provider_onboard](./images/flows_provider_onboard.jpg)

- **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 `published_apis.json` is updated with the API name and its ID.

**Required SDK inputs**:

- publisher_apf_id

- publisher_aefs_ids

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.

### Service Deletion

- **Function**: `unpublish_service()`

- **Script**: `provider_unpublish_api.py`

The SDK simplifies API deletion. Service deletion requires prior onboarding and service publication.

**Required SDK inputs**:

- service_api_id

- publisher_apf_id

- publisher_aefs_ids

### Service Updates

OpenCAPIF SDK references:

- **Function**: `update_service()`

- **Script**: `provider_update_api.py`

This function enables the updating of 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

- **Function**: `get_service()`

- **Script**: `provider_get_published_api.py`

Retrieve information on 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 on all previously published services, stored in `service_received.json`. Onboarding and service publication are required.

**Required SDK input**:

- **Functions**: `update_provider()` and `offboard_provider()`

- **Scripts**: `provider_capif_connector_update.py` and `provider_capif_connector_offboarding.py`

The provider must be onboarded before using these features. The `capif_sdk_config.json` must be edited for updates.

The provider must be onboarded before using these features.

![Provider_update-offboard](./images/flows_provider_update_offboard.jpg)

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)

The `token` variable is also available for retrieving the JWT token after the get_tokens() functionality.

The capif_api_details variable stores the `capif_api_security_context_details.json` content.

The invoker_capif_details variable stores the `capif_api_security_context_details.json` content.

### Invoker Onboarding

### Invoker onboarding

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`.

![Invoker_onboard](./images/flows_invoker_onboard.jpg)

### Service Discovery

- **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.

![Invoker_discover](./images/flows_invoker_discover.jpg)

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

- **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`.

![Invoker_get_token](./images/flows_invoker_get_tokens.jpg)

### Check authentication

OpenCAPIF SDK references:

- **Function**: `check_authentication()`

The SDK allows the API invoker to confirm the `supported_features` from the API exposing function(AEF).

It is important to have obtained the [JWT token](#obtain-jwt-tokens) previously. 

**Required SDK inputs**:

- check_authentication

![Invoker_check_authentication](./images/flows_invoker_check_authentication.jpg)

### 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. The `capif_sdk_config.json` must be edited for updates.

Onboarding is required before utilizing these functions.

![Invoker_update-offboard](./images/flows_invoker_update_offboard.jpg)