Commit 1ece6c08 authored by Jorge Moratinos's avatar Jorge Moratinos
Browse files

Merge branch 'develop' into 'main' 

Event feature completed

See merge request !4
parents 32e7392f f1a8c1bc

README.md

+16 −11
Original line number Diff line number Diff line
@@ -9,7 +9,7 @@ OpenCAPIF SDK provides a set of libraries to enable either CAPIF provider and in 


Current version of OpenCAPIF SDK is compatible with following publicly available releases:

- [OpenCAPIF Release 1.0](https://ocf.etsi.org/documentation/v1.0.0-release/)

- OpenCAPIF Release 2.0

- [OpenCAPIF Release 2.0](https://ocf.etsi.org/documentation/v2.0.0-release/)



This document serves as the [main bootstrap reference](#networkapp-developer-path) to start working with OpenCAPIF SDK. For advanced users, refer to [OpenCAPIF full documentation](./doc/sdk_full_documentation.md) section to dig into all available features.
@@ -63,7 +63,7 @@ Network Apps can be developed by third-party service providers, network operator 


Next image illustrates how CAPIF works and where the SDK provides means to integrate with it:



![CAPIF-illustration](./doc/images/flows_capif_illustration.jpg)

![CAPIF-illustration](./doc/images/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.
@@ -94,8 +94,12 @@ OpenCAPIF SDK brings a set of functions to integrate with the 5G Core's function 
| /{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)            |

| /api-invocation-logs/v1/{aefId}/logs (POST)             | [create_logs( aefId, api_invoker_id)](./doc/sdk_full_documentation.md#create_logs) | This operation allows to the Provider to notice to the CCF about the query of an invoker for an especific `aefId`

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

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



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)
@@ -105,7 +109,7 @@ NOTE: Above mentioned CAPIF APIs are defined in these 3GPP references: 
- [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.
@@ -121,6 +125,8 @@ To install the OpenCAPIF SDK source code for developing purposes there is an ava 


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

```
@@ -131,7 +137,7 @@ 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)

![sdk_data_schema](./doc/images/flows-data_schema.jpg)



# Network App developer path
@@ -143,7 +149,7 @@ Here is a good explanation about how a usual flow of a Network App should work: 


A Network App development running as a Provider would typically follow this process step by step, making use of the SDK:



![PROVIDER_PATH](./doc/images/flows_provider_path.jpg)

![PROVIDER_PATH](./doc/images/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.
@@ -154,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)

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

  provider.api_description_path = "./api_description_name.json"



  APF = provider.provider_capif_ids["APF-1"]
@@ -227,7 +233,7 @@ The `provider_capif_ids` variable stores the `provider_capif_ids.json` content i 


A Network App development running as an Invoker would typically follow this process step by step, making use of the SDK: 



![INVOKER_PATH](./doc/images/flows_invoker_path.jpg)

![INVOKER_PATH](./doc/images/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.
@@ -269,7 +275,6 @@ Code is next explained step by step: 
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](./samples/capif_api_security_context_details_sample.json) is also available.



Now, Invoker Network App can use access tokens to consume real services.
@@ -316,9 +321,9 @@ There are some features which **are not currently available at latest OpenCAPIF 


  - [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 Events API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Events_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

README_pipy.md

+7 −2
Original line number Diff line number Diff line
@@ -44,6 +44,11 @@ OpenCAPIF SDK brings a set of functions to integrate with the 5G Core's function 
| /{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)            |

| /api-invocation-logs/v1/{aefId}/logs (POST)             | [create_logs( aefId, api_invoker_id)](./doc/sdk_full_documentation.md#create_logs) | This operation allows to the Provider to notice to the CCF about the query of an invoker for an especific `aefId`

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

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



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)
@@ -52,10 +57,10 @@ 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)



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

config/capif_sdk_config.json

+38 −16
Original line number Diff line number Diff line
@@ -37,21 +37,21 @@ 
      "api-supported-features": "",

      "ue-ip-addr": "",

      "service-kpis": ""

    },

    "events": {

      "description": [""],

      "eventFilters": [

        {

          "apiIds": [""],

          "apiInvokerIds": [""],

          "aefIds": [""]

        }

      ]

    }

  },

  "provider": {

    "provider_folder": "",

    "supported_features": "",

    "apfs": "",

    "aefs": "",

    "publish_req": {

      "service_api_id": "",

      "publisher_apf_id": "",

      "publisher_aefs_ids": [

        "",

        ""

      ]

    },

    "cert_generation": {

      "csr_common_name": "",

      "csr_organizational_unit": "",
@@ -61,7 +61,29 @@ 
      "csr_country_name": "",

      "csr_email_address": ""

    },

    "apfs": "",

    "aefs": "",

    "publish_req": {

      "service_api_id": "",

      "publisher_apf_id": "",

      "publisher_aefs_ids": ["", ""]

    },

    "api_description_path": "",

    "events": {

      "description": [""],

      "eventFilters": [

        {

          "apiIds": [""],

          "apiInvokerIds": [""],

          "aefIds": [""]

        }

      ],

      "notificationDestination": "",

      "websockNotifConfig": {

        "websocketUri": "",

        "requestWebsocketUri": false

      }

    },

    "log": {

      "apiName": "",

      "apiVersion": "",

doc/images/capif_provider_details_example.png

deleted100644 → 0
−131 KiB
Loading image diff...