Commit c027a09a authored by Jorge Echevarria Uribarri's avatar Jorge Echevarria Uribarri Committed by GitHub
Browse files

SDK v0.2 (#3) 



PR:
- Improved documentation,
- Added and improved network-app samples,
- License draft v0.1.

---------

Co-authored-by: default avatarJorgeEcheva26 <jorge.echevarriauribarri.practicas@telefonica.es>
Co-authored-by: default avatarDaniel García <daniel.garciasanchez@telefonica.com>
parent a4467a1b

.gitignore

+6 −2
Original line number Original line Diff line number Diff line
@@ -163,8 +163,10 @@ cython_debug/ 




*/logs

*/logs







config

config







*.vscode

*.vscode





.flake8

.flake8
@@ -173,5 +175,7 @@ config 




*/__pycache__

*/__pycache__





*.capif_sdk_config_sample_test



test/capif_sdk_config_sample_test.json
 
*.capif_sdk_config_sample_test.json

/test/capif_sdk_config_sample_test.json

LICENSE

0 → 100644
+16 −0
Original line number Original line Diff line number Diff line 
Apache Software License 2.0

 

Copyright (c) 2021, Stavros Kolometsos

Copyright (c) 2024, Jorge Echevarría, Daniel García

 

Licensed under the Apache License, Version 2.0 (the “License”);

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

 

http://www.apache.org/licenses/LICENSE-2.0

 

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an “AS IS” BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.
 
 No newline at end of file

README.md

+55 −39
Original line number Original line Diff line number Diff line
@@ -12,6 +12,7 @@ Current version of OpenCAPIF SDK is compatible with following publicly available 
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.

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.





# Table of Contents

# Table of Contents



 1. [Repository structure](#repository-structure) 

 1. [Repository structure](#repository-structure) 

 2. [Network App developers](#network-app-developers)

 2. [Network App developers](#network-app-developers)

 3. [OpenCAPIF SDK summary](#opencapif-sdk-summary)

 3. [OpenCAPIF SDK summary](#opencapif-sdk-summary)
@@ -26,6 +27,7 @@ This document serves as the [main bootstrap reference](#networkapp-developer-pat 
 8. [OpenCAPIF SDK known issues](#opencapif-sdk-known-issues)

 8. [OpenCAPIF SDK known issues](#opencapif-sdk-known-issues)

 9. [OpenCAPIF SDK developers](./doc/sdk_developers.md)

 9. [OpenCAPIF SDK developers](./doc/sdk_developers.md)







# Repository structure

# Repository structure





    pesp_capif_sdk

    pesp_capif_sdk
@@ -65,11 +67,13 @@ 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.

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

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



  - 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





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

**Network Apps developers are the target users of OpenCAPIF SDK.**
@@ -86,7 +90,7 @@ OpenCAPIF SDK brings a set of functions to integrate with the 5G Core's function 
| /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/{registrationId} (PUT)                 | [update_provider()](./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`.                  |

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

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

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

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

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

| /{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(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} (DELETE)         | [unpublish_service()](./doc/sdk_full_documentation.md#services-deletion)                                         | Deletes a service API from the system for a specific `apfId`and `serviceApiId`                      |
@@ -95,6 +99,7 @@ OpenCAPIF SDK brings a set of functions to integrate with the 5G Core's function 
| /{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`            |

| /{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`            |











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

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 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 Provider API specification](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_API_Provider_Management_API.yaml)
@@ -128,16 +133,15 @@ Now, it is described in 4 simple steps how a Provider can be developed in just s 
```python

```python

  provider = capif_provider_connector(config_file="path/to/the/capif_sdk_config.json")

  provider = capif_provider_connector(config_file="path/to/the/capif_sdk_config.json")

  provider.onboard_provider()

  provider.onboard_provider()

  capif_connector.api_description_path = "./nef-upf-partner-1.json"

  provider.api_description_path = "./nef_upf_vendor_1.json"

  provider_folder = capif_connector.provider_folder





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

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





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

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

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

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





  capif_connector.publish_req['publisher_apf_id'] = APF

  provider.publish_req['publisher_apf_id'] = APF

  capif_connector.publish_req['publisher_aefs_ids'] = [AEF1, AEF2]

  provider.publish_req['publisher_aefs_ids'] = [AEF1, AEF2]

  provider.publish_services()

  provider.publish_services()

```

```
@@ -168,7 +172,7 @@ Code is next explained step by step: 




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

    The api_prov_funcs 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 capif_connector.

    This publish_req field can also be filled with object variables already stored at provider object.





4. **Publish the services:** \

4. **Publish the services:** \

   Use the publish_services() method to register the APIs with the CAPIF framework(don't forget to update the capif_provider_connector constructor in order to use the new APF and AEFs):

   Use the publish_services() method to register the APIs with the CAPIF framework(don't forget to update the capif_provider_connector constructor in order to use the new APF and AEFs):
@@ -192,9 +196,15 @@ Within the `provider_folder`, the SDK stores the created folders named with pref 
- `capif_provider_details.json`: contains all the APFs and AEFs ids that have already onboarded with this `capif_username`,

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

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

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

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







All the configuration values are available within the object capif_provider_connector, also the api_prov_funcs variable is a dict which contains as a key all the APFs and AEFs, as a value contains all APFs and AEFs ids.









## Invoker Network App

## Invoker Network App
@@ -208,9 +218,10 @@ Now, it is described in some simple steps how an Invoker can be developed in jus 
```python

```python

  invoker = capif_invoker_connector(config_file="path/to/the/capif_sdk_config.json")

  invoker = capif_invoker_connector(config_file="path/to/the/capif_sdk_config.json")

  invoker.onboard_invoker()

  invoker.onboard_invoker()

  service_discoverer = ServiceDiscoverer(config_file=utilities.get_config_file())

  service_discoverer = service_discoverer(config_file="path/to/the/capif_sdk_config.json")

  service_discoverer.discover()

  service_discoverer.discover()

  service_discoverer.get_tokens()

  service_discoverer.get_tokens()

  jwt_token=service_discoverer.token

```

```





Code is next explained step by step:

Code is next explained step by step:
@@ -277,16 +288,21 @@ In the `invoker_folder`, it will be located several folders with each `capif_use 
    2. If the Service Discovery Functionality has already been used , it will be found all the available APIs with their information,

    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.

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





# OpenCAPIF SDK known issues

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

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 Access control policy management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Access_Control_Policy_API.yaml)

  - [CAPIF Events API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Events_API.yaml),

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

  - [CAPIF Routing info API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Routing_Info_API.yaml),

  - [CAPIF Logging API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Logging_API_Invocation_API.yaml)

  - [CAPIF Security API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Security_API.yaml):

  - [CAPIF Routing info API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Routing_Info_API.yaml)

    - /trustedInvokers/{apiInvokerId}/delete (POST),

  - [CAPIF Security API management](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Security_API.yaml)

    - /trustedInvokers/{apiInvokerId} (GET),

    - /trustedInvokers/{apiInvokerId}/delete (POST)

    - /trustedInvokers/{apiInvokerId} (DELETE).
 
    - /trustedInvokers/{apiInvokerId} (GET)

    - /trustedInvokers/{apiInvokerId} (DELETE)

  - [AEF_Security_API](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_AEF_Security_API.yaml)

config/capif_sdk_config.json

+35 −33
Original line number Original line Diff line number Diff line 
{

{

  "capif_host": "capif-prev.mobilesandbox.cloud",

  "capif_host": "",

  "register_host": "registercapif-prev.mobilesandbox.cloud",

  "register_host": "",

  "capif_https_port": "36212",

  "capif_https_port": "",

  "capif_register_port": "36211",

  "capif_register_port": "",

  "capif_username": "echeva_0",

  "capif_username": "",

  "capif_password": "echevapass",

  "capif_password": "",

  "debug_mode": "False",

  "debug_mode": "",

  "invoker": {

  "invoker": {

    "invoker_folder": "/Users/IDB0128/Documents/OpenCapif/test_invoker_certificate_folder",

    "invoker_folder": "",

    "capif_callback_url": "http://localhost:5000",

    "capif_callback_url": "",

    "cert_generation": {

    "cert_generation": {

      "csr_common_name": "invoker",

      "csr_common_name": "",

      "csr_organizational_unit": "test_app_ou",

      "csr_organizational_unit": "",

      "csr_organization": "test_app_o",

      "csr_organization": "",

      "crs_locality": "Madrid",

      "crs_locality": "",

      "csr_state_or_province_name": "Madrid",

      "csr_state_or_province_name": "",

      "csr_country_name": "ES",

      "csr_country_name": "",

      "csr_email_address": "test@example.com"

      "csr_email_address": ""



    },

    },

    "discover_filter": {

    "discover_filter": {

      "api-name": "",

      "api-name": "",
@@ -34,10 +35,11 @@ 
      "service-kpis": ""

      "service-kpis": ""

    }

    }

  },

  },



  "provider": {

  "provider": {

    "provider_folder": "/Users/IDB0128/Documents/OpenCapif/test_provider_certificate_folder",

    "provider_folder": "",

    "apfs": "1",

    "apfs": "",

    "aefs": "2",

    "aefs": "",

    "publish_req": {

    "publish_req": {

      "service_api_id": "",

      "service_api_id": "",

      "publisher_apf_id": "",

      "publisher_apf_id": "",
@@ -47,14 +49,14 @@ 
      ]

      ]

    },

    },

    "cert_generation": {

    "cert_generation": {

      "csr_common_name": "provider",

      "csr_common_name": "",

      "csr_organizational_unit": "test_app_ou",

      "csr_organizational_unit": "",

      "csr_organization": "test_app_o",

      "csr_organization": "",

      "crs_locality": "Madrid",

      "crs_locality": "",

      "csr_state_or_province_name": "Madrid",

      "csr_state_or_province_name": "",

      "csr_country_name": "ES",

      "csr_country_name": "",

      "csr_email_address": "test@example.com"

      "csr_email_address": ""

    },

    },

    "api_description_path": "/Users/IDB0128/git_repos/pesp_capif_sdk/samples/provider_api_description_sample.json"

    "api_description_path": ""

   }

   }

}
 
}

doc/images/OpenCAPIF_icon.jpg

0 → 100644
+7.05 KiB
Loading image diff...