Commit 813a1af0 authored by Jorge Moratinos's avatar Jorge Moratinos
Browse files

Merge branch 'develop' into 'main' 

future updates, upgrade of api translator and adaptation to supported features...

See merge request !5
parents 1ece6c08 ed0470cc

README.md

+11 −11
Original line number Diff line number Diff line
@@ -80,26 +80,26 @@ OpenCAPIF SDK brings a set of functions to integrate with the 5G Core's function 


| **3GPP CAPIF API**                                    | **OpenCAPIF SDK function**                                  | **Description**                                             |

|-------------------------------------------------------|-------------------------------------------------------------|-------------------------------------------------------------|

| /onboardedInvokers (POST)                             | [onboard_invoker()](./doc/sdk_full_documentation.md#invoker-onboarding)                                           | Registers a new invoker.                                    |

| /onboardedInvokers/{onboardingId} (PUT)               | [update_invoker()](./doc/sdk_full_documentation.md#update-and-offboard-invoker)                                          | Updates an existing invoker for a specific `onboardingId`.                                |

| /onboardedInvokers (POST)                             | [onboard_invoker(supp_features)](./doc/sdk_full_documentation.md#invoker-onboarding)                                           | Registers a new invoker.                                    |

| /onboardedInvokers/{onboardingId} (PUT)               | [update_invoker(supp_features)](./doc/sdk_full_documentation.md#update-and-offboard-invoker)                                          | Updates an existing invoker for a specific `onboardingId`.                                |

| /onboardedInvokers/{onboardingId} (DELETE)            | [offboard_invoker()](./doc/sdk_full_documentation.md#update-and-offboard-invoker)                                         | Deletes an invoker for a specific `onboardingId`.                                         |

| registrations (POST)                                  | [onboard_provider()](./doc/sdk_full_documentation.md#provider-onboarding)                                          | Registers a new service provider.                           |

| /registrations/{registrationId} (PUT)                 | [update_provider()](./doc/sdk_full_documentation.md#update-and-offboard-provider)                                           | Updates a service provider's registration for a specific `registrationId`.                  |

| registrations (POST)                                  | [onboard_provider(supp_features)](./doc/sdk_full_documentation.md#provider-onboarding)                                          | Registers a new service provider.                           |

| /registrations/{registrationId} (PUT)                 | [update_provider(supp_features)](./doc/sdk_full_documentation.md#update-and-offboard-provider)                                           | Updates a service provider's registration for a specific `registrationId`.                  |

| /registrations/{registrationId} (DELETE)              | [offboard_provider()](./doc/sdk_full_documentation.md#update-and-offboard-provider)                                         | Deletes a service provider's registration for a specific `registrationId`.                  |

| /allServiceAPIs (GET)                                 | [discover()](./doc/sdk_full_documentation.md#discover-process)                                                  | Retrieves a list of all available service APIs.             |

| /trustedInvokers (PUT//POST)                          | [get_tokens()](./doc/sdk_full_documentation.md#discover-process)                                                  | Registers or updates trusted invokers.                      |

| /securities/{securityId}/token (GET)                  | [get_tokens()](./doc/sdk_full_documentation.md#obtain-invoker-tokens)                                                | Retrieves a security token for a specific `securityId`. This JWT token is used to query the targeted services.      |

| /trustedInvokers (PUT//POST)                          | [get_tokens(supp_features)](./doc/sdk_full_documentation.md#discover-process)                                                  | Registers or updates trusted invokers.                      |

| /securities/{securityId}/token (GET)                  | [get_tokens(supp_features)](./doc/sdk_full_documentation.md#obtain-invoker-tokens)                                                | Retrieves a security token for a specific `securityId`. This JWT token is used to query the targeted services.      |

| /{apfId}/service-apis(POST)                           | [publish_services()](./doc/sdk_full_documentation.md#services-publishing)                                          | Registers a new service API into the system for a specific `apfId`                |

| /{apfId}/service-apis/{serviceApiId} (DELETE)         | [unpublish_service()](./doc/sdk_full_documentation.md#services-deletion)                                         | Deletes a service API from the system for a specific `apfId`and `serviceApiId`                      |

| /{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(supported_features)](./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)            |

| /api-invocation-logs/v1/{aefId}/logs (POST)             | [create_logs(aefId, jwt)](./doc/sdk_full_documentation.md#create_logs) | 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)](./doc/sdk_full_documentation.md#create_subscription) | This operation allows to the Invoker/AEF/APF/AMF to ask to the CCF about notifications related to certain functionalities.

| /api-invocation-logs/v1/{aefId}/logs (POST)             | [create_logs(aefId, jwt,supp_features)](./doc/sdk_full_documentation.md#create_logs) | 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)](./doc/sdk_full_documentation.md#create_subscription) | 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)](./doc/sdk_full_documentation.md#delete_subscription) | 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)](./doc/sdk_full_documentation.md#update_subscription) | 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)](./doc/sdk_full_documentation.md#patch_subscription) | 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} (PUT)             | [update_subscription(name, id, supp_features)](./doc/sdk_full_documentation.md#update_subscription) | 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)](./doc/sdk_full_documentation.md#patch_subscription) | 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)
@@ -160,7 +160,7 @@ Now, it is described in 4 simple steps how a Provider can be developed in just s 
  provider.onboard_provider()



  #translator = opencapif_sdk.api_schema_translator("./path/to/openapi.yaml")

  #translator.build("api_description_name",ip="0.0.0.0",port=9090,supported_features="0",api_supp_features="0")

  #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"]

README_pipy.md

+70 −175

File changed.

Preview size limit exceeded, changes collapsed.

doc/sdk_developers.md

+1 −1
Original line number Diff line number Diff line
@@ -56,7 +56,7 @@ This article explains how to solve it [here](https://laict.medium.com/install-py 
2. Clone GitHub repository:



```console

git clone https://github.com/Telefonica/pesp_capif_sdk.git

git clone https://labs.etsi.org/rep/ocf/sdk.git

```



```console

doc/sdk_full_documentation.md

+29 −11
Original line number Diff line number Diff line
@@ -12,7 +12,6 @@ Before using the SDK, the following steps should be completed: 
- 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/flows-updated_opencapif.jpg)
@@ -72,10 +71,12 @@ The provider_capif_ids variable stores the `provider_service_ids.json` content i 
### Provider Onboarding



OpenCAPIF SDK references:

- **Function**: `onboard_provider()`

- **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.It's default value its 0.





![Provider_onboard](./images/flows-provider_onboard.jpg)
@@ -153,12 +154,14 @@ Retrieve information about all previously published services in `service_receive 
### Update and Offboard Provider



OpenCAPIF SDK references:

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

- **Functions**: `update_provider(supp_features)` 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...

`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.It's default value its 0.



The provider must be onboarded before using these features.



![Provider_update-offboard](./images/flows-provider_update_offboard.jpg)
@@ -166,10 +169,12 @@ The provider must be onboarded before using these features. 
### Create logs



OpenCAPIF SDK references:

- **Function**: `create_logs(aefId, jwt)`

- **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.It's default value its 0.



For leveraging this feature the Provider must have onboarded and published an API previously.



**Required SDK input**:
@@ -182,10 +187,12 @@ For leveraging this feature the Provider must have onboarded and published an AP 
### Create subscription



OpenCAPIF SDK references:

- **Function**: `create_subscription(name, id)`

- **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.It's default value its 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.
@@ -213,12 +220,14 @@ For leveraging this feature the Provider must have onboarded and created a subsc 
### Update subscription



OpenCAPIF SDK references:

- **Function**: `update_subscription(name, id)`

- **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.It's default value its 0.



For leveraging this feature the Provider must have onboarded and created a subscription previously.



![Events_feature](./images/flows-event_subscription.jpg)
@@ -238,6 +247,8 @@ OpenCAPIF SDK references: 


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.It's default value its 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#events_configuration)



For leveraging this feature the Provider must have onboarded and created a subscription previously.
@@ -271,11 +282,14 @@ The invoker_capif_details variable stores the `capif_api_security_context_detail 
### Invoker onboarding



OpenCAPIF SDK references:

- **Function**: `onboard_invoker()`

- **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.It's default value its 0.





![Invoker_onboard](./images/flows-invoker_onboard.jpg)



### Service Discovery
@@ -295,10 +309,11 @@ Use the [discover_filter](./sdk_configuration.md) to retrieve access to target A 
### Obtain JWT Tokens



OpenCAPIF SDK references:

- **Function**: `get_tokens()`

- **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.It's default value its 0.



![Invoker_get_token](./images/flows-invoker_get_tokens.jpg)
@@ -319,11 +334,14 @@ 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()`

- **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.It's default value its 0.





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



## Other Features
@@ -337,7 +355,7 @@ This schema could be obtained by applying this code. 
    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,supported_features="0",api_supp_features="0")

    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.