diff --git a/.DS_Store b/.DS_Store index d99119780fb8ea0b49729f7fd11b37ecb0c1161e..f3245c94bb7e296b74b5306ae4bd8710b64bfd41 100644 Binary files a/.DS_Store and b/.DS_Store differ diff --git a/README.md b/README.md index e94585b08b51e2c47db226cb8164a9317aa310c2..157418b3feacae01b2e9a71569777a59696bdcd0 100644 --- a/README.md +++ b/README.md @@ -9,245 +9,15 @@ This repository develop a Python Software Development Kit(SDK) whis focuses on c OpentCAPIF SDK provides a set of libraries to enable either CAPIF provider and invoker roles, and other functions to simplify procedures calls towards OpenCAPIF. Current version of OpenCAPIF SDK is compatible with following publicly available releases: -- OpenCAPIF Release 1.0 [LINK TO OPENCAPIF RELEASE](https://ocf.etsi.org/documentation/v1.0.0-release/) +- [OpenCAPIF Release 1.0](https://ocf.etsi.org/documentation/v1.0.0-release/) # Table of Contents - 1. [OpenCAPIF SDK usage](#OpenCAPIF-SDK-usage) - 2. [OpenCAPIF SDK Features](#OpenCAPIF-SDK-Features) - 3. [OpenCAPIF SDK Installation](#OpenCAPIF-SDK-Installation) - 4. [How to use OpenCAPIF SDK](#How-to-use-OpenCAPIF-SDK) - 5. [OpenCAPIF SDK known issues](#OpenCAPIF-SDK-known-issues) - 6. [DEV ENVIRONMENT] (/doc/sdk-dev-env.md) + 1. [OpenCAPIF SDK Features](./doc/sdk-features.md) + 2. [OpenCAPIF SDK Prerequesites](./doc/sdk-prerequesites.md) + 3. [OpenCAPIF SDK Installation](./doc/sdk-installation.md) + 4. [OpenCAPIF SDK Configuration](./doc/sdk-configuration.md) + 5. [OpenCAPIF SDK Usage](./doc/sdk-usage.md) + 6. [OpenCAPIF SDK known issues](./doc/sdk-issues.md) -# OpenCAPIF SDK usage -OpenCAPIF SDK implements this set of features to easily integrate an application with CAPIF NF either manually or integrating SDK library directly within app code. - -[GENERAL CAPIF USAGE FLOW] - -This repository includes 2 different modes to test OpenCAPIF SDK: -- **Manual usage**: use a set of python scripts to test step by step all implemented procedures. All of them are provided at scripts folder, -[IMAGE OF ARCH APP ----> CAPIF WITH SCRIPTS] - -- **Development usage**: import SDK in your code and start ... Within nf-sample folder, it is provided a sample application leveraging -[IMAGE OF ARCH APP ----> CAPIF WITH SDK INTEGRATION] - -# OpenCAPIF SDK Features -LO QUE HE IMPLEMENTADO DE OPENCAPIF == RELEASE NOTES - - -# OpenCAPIF SDK scripts - -This repository provides manual scripts to validate and demonstrate the integration to OpenCAPIF. Next are listed the behaviour of all of them available at /sctipts folder: -1. -2. -3. -4. - -Additional requests to CAPIF: -- Publisher: addionally a devoloper could retrieve data from ... - 1. - 2. - -- Events: blah blah - -- Explore API directory: - - -- **Invoker CAPIF connector**: Simplifies the process of onboarding for Invoker users, -- **Provider CAPIF connector**: Simplifies the process of onboarding for Provider users,also has the capability to register several APF's and AEF's if its necesary, -- **Invoker Service Discovery**: Facilitates making a Discovery request to CAPIF, also stores the API services recieved and has an option to filter them, -- **Invoker Service Get token**: After the Discovery, this functionality simplifies the way of getting created their propperly security context for each of the services and adquiring the access token to use the final APIs, -- **Provider Publish API**: Simplifies the process of publishing an API. Also has the capability to chose which APF and AEF's will be used to publish the API, -- **Provider Unpublish API**: Simplifies the process of deleting an API, -- **Provider Update API**: Simplifies the process of updating an API. Also has the capability to chose which APF and AEF's will be used to update the API, -- **Provider Get API**: Simplifies the process of recieving the information of One service published previously, -- **Provider Get all APIs**: Simplifies the process of recieving the information of all available services published previously, -- **Invoker CAPIF connector offboarding**: Simplifies the process of offboarding for Invoker users, -- **Provider CAPIF connector offboarding**: Simplifies the process of offboarding for Provider users. - -[OPENCAPIF SDK CODE STRUCTURE] - - - - -## Other features - -Apart from the SDK core, there are available different functionalities for development purposes: - -- **Register and login**: Facilitates the logging process for admin users and creates a CAPIF user, -- **Deregister and login**: Facilitates the logging process for admin users and eliminates a CAPIF user. - - - -# How to use OpenCAPIF SDK - -1 - First it is required to complete the utilities file with the absolute paths of target environment in order to complete the configuration of the SDK: -- NOTE register file is not needed for the use of the SDK, -- NOTE provider_exposer_get_sample_api_description_path is mandatory if publish functionalities are required. - -2 - Then it is needed to fill out config files depending on the features required to be used from the SDK. - -## OpenCAPIF SDK prerequisites - -IMPORTANT: In order to leverage OpenCAPIF SDK it is required to have registered a user in the target CAPIF instance, so contact administrator to have required predefined credentials (username and password). - -## OpenCAPIF SDK configuration - -### 1. Configuration via Config.json - -This configuration could also be fullfilled by enviroment variables (EXAMPLE) - -Mandatory fields no matter the target role to be onboarded, either invoker or provider: - -- capif_host -- register_host -- capif_https_port -- capif_register_port -- capif_username -- capif_password -- debug_mode - -If you want to use SDK as an **Invoker** you need to fill out these fields - -- invoker_folder -- capif_callback_url -- csr_information(csr_common_name,csr_country_name...) - -If you want to use SDK as a **Provider** you need to fill out these fields - -- provider_folder -- APFs -- AEFs - - - - - - - "invoker_folder": String | The path (relative or absolute) of the folder you want to store your invoker information - - "provider_folder": String | The path (relative or absolute) of the folder you want to store your invoker information - - "capif_host": String | The domain name of your capif host - - "register_host": String | The domain name of your register host - - "capif_https_port": Integer | The port of your capif host - - "capif_register_port": Integer | The port of your register host - - "capif_callback_url": String | The Url you want to recieve CAPIF notifications(This functionality is not currently available) - - "csr_common_name": String | Information for your invoker certificate - - "csr_organizational_unit": String | Information for your invoker certificate - - "csr_organization": String | Information for your invoker certificate - - "crs_locality": String | Information for your invoker certificate - - "csr_state_or_province_name": String |Information for your invoker certificate - - "csr_country_name": String | Information for your invoker certificate - - "csr_email_address": String | Information for your invoker certificate - - "capif_username": String | CAPIF username - - "capif_password": String | CAPIF password - - "APFs": Integer | Number of APF's you want to onboard as a provider Example:5 - - "AEFs": Integer | Number of AEF's you want to onboard as a provider Example:2 - - "debug_mode": Boolean | If you want to recieve logs from SDK-S6G Example:True/False - -### 2. Configuration of Publish.json - - "serviceApiId": String | The Api id we want to use Example "02eff6e1b3a8f7c8044a92ee8a30bd" - "publisherAPFid": String | APF id we chose to use Example : "APFa165364a379035d14311deadc04332" - "publisherAEFsids": Array | Array of strings filled out of AEFs ids we want to use Example: ["AEFfa38f0e855bffb420e4994ecbc8fb9","AEFe8bfa711f4f0c95ba0b382508e6382"] - -ServiceApiId is required in: -- Provider Unpublish Api -- Provider Update Api -- Provider Get api - -PublisherAPFid is required in: - -- Provider Publish Api -- Provider Unpublish Api -- Provider Update Api -- Provider Get Api -- Provider Get all Apis - -PublisherAEFsids is required in: - -- Provider Publish Api -- Provider Unpublish Api -- Provider Update Api - -For using the Publish Api function or the Update function you **must** modify the provider_api_description_sample.json with the Publish API that you want to share following the standard schema for [ServiceAPIDescription](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Publish_Service_API.yaml) - -You won't need to fill out the aefIds fields from aefProfiles array because you would already be configurating this fields by completing publisherAEFsids parameter - -If the publisherAEFsids parameter don't match with the aefProfiles you will recieve an error - -### Important information for Provider consumer - -In the provider_folder, you will find several folders with each capif_username you have onboarded as a provider, for each folder you could find: - -- Capif_provider_details.json : Contains all the APFs and AEFs ids you have already onboarded with this capif_username -- CAPIF_provider_api_description_sample.json : If you already published or updated an API, you will find a copy of your last payload. -- Service_received.json : If you already used the get an api or get all apis functionality, you will find the response to your request. -- Published-Apis.json : Constains the currently published APIs with their ApiId - -#### Configuration of Discover_filter.json -This file follows the parameters schema from the GET petition of [Discover Services API](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Discover_Service_API.yaml) - -To use this feature you must complete the file with the parameters you want to be filtered and then run the Invoker Service Discovery Functionality. - -To run the Invoker Service Discovery Functionality you must have onboarded as an Invoker before. - -### Important information for Invoker consumer - -In the `invoker_folder`, you will find several folders with each `capif_username` you have onboarded as a provider. For each folder, you could find: - -- `Capif_api_security_context_details.json`: This file contains the information of your invoker. It will contain: - - 1. Your `api_invoker_id`. - 2. If you have already used the Service Discovery Functionality, you will find all the available APIs with their information. - 3. If you have already used the Service Get Token functionality, you will find your access token for using the APIs you have already discovered. - -By default, the Service Get Token will get the access token for using all the APIs that are available. So if you want to filter the APIs and reach only the API you want, you must: - -1. Complete your `Discover_filter.json` file. -2. Use the Service Discovery Functionality. -3. Use the Service Get Token Functionality. - -#### Configuration of Register.json - - - "register_host": String | The domain name of your register host - "capif_register_port": Integer | The port of your register host - "capif_register_username": String | CAPIF admin username - "capif_register_password": String | CAPIF admin password - "capif_username": String | CAPIF user username - "capif_password": String | CAPIF user password - "config_path": String | Absolute path to the Config_files folder - "uuid": String | UUID for Deregistering the user - - -This file is only used for the Functionalities of : -- Register and login -- Deregister and login - -Each field is obligatory to complete except UUID, which is only obligatory in case of Deregistering the user. - -Although this field is not obligatory we recomend to store the UUID parameter recieved by the Register and login functionality in this field. - -# OpenCAPIF SDK known issues - -[TO PUT HERE ALL KNOWN ISSUES OR BACKLOG] \ No newline at end of file diff --git a/doc/sdk-configuration.md b/doc/sdk-configuration.md new file mode 100644 index 0000000000000000000000000000000000000000..c3b8412dacf11cc27eb3ab830621fda2a7c5203f --- /dev/null +++ b/doc/sdk-configuration.md @@ -0,0 +1,154 @@ +## OpenCAPIF SDK configuration + +### 1. Configuration via Config.json + +This configuration could also be fullfilled by enviroment variables (EXAMPLE) + +Mandatory fields no matter the target role to be onboarded, either invoker or provider: + +- capif_host +- register_host +- capif_https_port +- capif_register_port +- capif_username +- capif_password +- debug_mode + +If you want to use SDK as an **Invoker** you need to fill out these fields + +- invoker_folder +- capif_callback_url +- csr_information(csr_common_name,csr_country_name...) + +If you want to use SDK as a **Provider** you need to fill out these fields + +- provider_folder +- APFs +- AEFs + + + + + + + "invoker_folder": String | The path (relative or absolute) of the folder you want to store your invoker information + + "provider_folder": String | The path (relative or absolute) of the folder you want to store your invoker information + + "capif_host": String | The domain name of your capif host + + "register_host": String | The domain name of your register host + + "capif_https_port": Integer | The port of your capif host + + "capif_register_port": Integer | The port of your register host + + "capif_callback_url": String | The Url you want to recieve CAPIF notifications(This functionality is not currently available) + + "csr_common_name": String | Information for your invoker certificate + + "csr_organizational_unit": String | Information for your invoker certificate + + "csr_organization": String | Information for your invoker certificate + + "crs_locality": String | Information for your invoker certificate + + "csr_state_or_province_name": String |Information for your invoker certificate + + "csr_country_name": String | Information for your invoker certificate + + "csr_email_address": String | Information for your invoker certificate + + "capif_username": String | CAPIF username + + "capif_password": String | CAPIF password + + "APFs": Integer | Number of APF's you want to onboard as a provider Example:5 + + "AEFs": Integer | Number of AEF's you want to onboard as a provider Example:2 + + "debug_mode": Boolean | If you want to recieve logs from SDK-S6G Example:True/False + +### 2. Configuration of Publish.json + + "serviceApiId": String | The Api id we want to use Example "02eff6e1b3a8f7c8044a92ee8a30bd" + "publisherAPFid": String | APF id we chose to use Example : "APFa165364a379035d14311deadc04332" + "publisherAEFsids": Array | Array of strings filled out of AEFs ids we want to use Example: ["AEFfa38f0e855bffb420e4994ecbc8fb9","AEFe8bfa711f4f0c95ba0b382508e6382"] + +ServiceApiId is required in: +- Provider Unpublish Api +- Provider Update Api +- Provider Get api + +PublisherAPFid is required in: + +- Provider Publish Api +- Provider Unpublish Api +- Provider Update Api +- Provider Get Api +- Provider Get all Apis + +PublisherAEFsids is required in: + +- Provider Publish Api +- Provider Unpublish Api +- Provider Update Api + +For using the Publish Api function or the Update function you **must** modify the provider_api_description_sample.json with the Publish API that you want to share following the standard schema for [ServiceAPIDescription](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Publish_Service_API.yaml) + +You won't need to fill out the aefIds fields from aefProfiles array because you would already be configurating this fields by completing publisherAEFsids parameter + +If the publisherAEFsids parameter don't match with the aefProfiles you will recieve an error + +### Important information for Provider consumer + +In the provider_folder, you will find several folders with each capif_username you have onboarded as a provider, for each folder you could find: + +- Capif_provider_details.json : Contains all the APFs and AEFs ids you have already onboarded with this capif_username +- CAPIF_provider_api_description_sample.json : If you already published or updated an API, you will find a copy of your last payload. +- Service_received.json : If you already used the get an api or get all apis functionality, you will find the response to your request. +- Published-Apis.json : Constains the currently published APIs with their ApiId + +#### Configuration of Discover_filter.json +This file follows the parameters schema from the GET petition of [Discover Services API](https://github.com/jdegre/5GC_APIs/blob/Rel-18/TS29222_CAPIF_Discover_Service_API.yaml) + +To use this feature you must complete the file with the parameters you want to be filtered and then run the Invoker Service Discovery Functionality. + +To run the Invoker Service Discovery Functionality you must have onboarded as an Invoker before. + +### Important information for Invoker consumer + +In the `invoker_folder`, you will find several folders with each `capif_username` you have onboarded as a provider. For each folder, you could find: + +- `Capif_api_security_context_details.json`: This file contains the information of your invoker. It will contain: + + 1. Your `api_invoker_id`. + 2. If you have already used the Service Discovery Functionality, you will find all the available APIs with their information. + 3. If you have already used the Service Get Token functionality, you will find your access token for using the APIs you have already discovered. + +By default, the Service Get Token will get the access token for using all the APIs that are available. So if you want to filter the APIs and reach only the API you want, you must: + +1. Complete your `Discover_filter.json` file. +2. Use the Service Discovery Functionality. +3. Use the Service Get Token Functionality. + +#### Configuration of Register.json + + + "register_host": String | The domain name of your register host + "capif_register_port": Integer | The port of your register host + "capif_register_username": String | CAPIF admin username + "capif_register_password": String | CAPIF admin password + "capif_username": String | CAPIF user username + "capif_password": String | CAPIF user password + "config_path": String | Absolute path to the Config_files folder + "uuid": String | UUID for Deregistering the user + + +This file is only used for the Functionalities of : +- Register and login +- Deregister and login + +Each field is obligatory to complete except UUID, which is only obligatory in case of Deregistering the user. + +Although this field is not obligatory we recomend to store the UUID parameter recieved by the Register and login functionality in this field. diff --git a/doc/sdk-features.md b/doc/sdk-features.md new file mode 100644 index 0000000000000000000000000000000000000000..8f3cd24b8e7d923baaed75b1606886a54905e04a --- /dev/null +++ b/doc/sdk-features.md @@ -0,0 +1,34 @@ +# OpenCAPIF SDK Features + +## CAPIF_API_Invoker_management API + +- Onboard_API_Invoker + +- Offboard_API_Invoker + +## CAPIF_API_Provider_Management_API + +- Onboard_API_Provider + +- Update_API_Provider + +- Offboard_API_Provider + +## CAPIF_Discover_Service_API + +- Discover_Service_API + +## CAPIF_Publish_Service_API + +- Publish_Service_API + +- Unpublish_Service_API + +- Update_Service_API + +- Get_Service_API + + + + + diff --git a/doc/sdk-dev-env.md b/doc/sdk-installation.md similarity index 100% rename from doc/sdk-dev-env.md rename to doc/sdk-installation.md diff --git a/doc/sdk-issues.md b/doc/sdk-issues.md new file mode 100644 index 0000000000000000000000000000000000000000..f9c23a0330f5dc4437fa6f2b0fa13fa4e95e15c8 --- /dev/null +++ b/doc/sdk-issues.md @@ -0,0 +1,3 @@ +# OpenCAPIF SDK known issues + +[TO PUT HERE ALL KNOWN ISSUES OR BACKLOG] \ No newline at end of file diff --git a/doc/sdk-prerequesites.md b/doc/sdk-prerequesites.md new file mode 100644 index 0000000000000000000000000000000000000000..eb10a656244cafc49bbd075300a031814252ebbe --- /dev/null +++ b/doc/sdk-prerequesites.md @@ -0,0 +1,3 @@ +## OpenCAPIF SDK prerequisites + +IMPORTANT: In order to leverage OpenCAPIF SDK it is required to have registered a user in the target CAPIF instance, so contact administrator to have required predefined credentials (username and password). diff --git a/doc/sdk-usage.md b/doc/sdk-usage.md new file mode 100644 index 0000000000000000000000000000000000000000..292f607fd3749aa52d89a8febb1ce0984798db79 --- /dev/null +++ b/doc/sdk-usage.md @@ -0,0 +1,68 @@ +# OpenCAPIF SDK usage + +OpenCAPIF SDK implements this set of features to easily integrate an application with CAPIF NF either manually or integrating SDK library directly within app code. + +[GENERAL CAPIF USAGE FLOW] + +This repository includes 2 different modes to test OpenCAPIF SDK: +- **Manual usage**: use a set of python scripts to test step by step all implemented procedures. All of them are provided at scripts folder, +[IMAGE OF ARCH APP ----> CAPIF WITH SCRIPTS] + +- **Development usage**: import SDK in your code and start ... Within nf-sample folder, it is provided a sample application leveraging +[IMAGE OF ARCH APP ----> CAPIF WITH SDK INTEGRATION] + + +# OpenCAPIF SDK scripts + +This repository provides manual scripts to validate and demonstrate the integration to OpenCAPIF. Next are listed the behaviour of all of them available at /sctipts folder: +1. +2. +3. +4. + +Additional requests to CAPIF: +- Publisher: addionally a devoloper could retrieve data from ... + 1. + 2. + +- Events: blah blah + +- Explore API directory: + + +- **Invoker CAPIF connector**: Simplifies the process of onboarding for Invoker users, +- **Provider CAPIF connector**: Simplifies the process of onboarding for Provider users,also has the capability to register several APF's and AEF's if its necesary, +- **Invoker Service Discovery**: Facilitates making a Discovery request to CAPIF, also stores the API services recieved and has an option to filter them, +- **Invoker Service Get token**: After the Discovery, this functionality simplifies the way of getting created their propperly security context for each of the services and adquiring the access token to use the final APIs, +- **Provider Publish API**: Simplifies the process of publishing an API. Also has the capability to chose which APF and AEF's will be used to publish the API, +- **Provider Unpublish API**: Simplifies the process of deleting an API, +- **Provider Update API**: Simplifies the process of updating an API. Also has the capability to chose which APF and AEF's will be used to update the API, +- **Provider Get API**: Simplifies the process of recieving the information of One service published previously, +- **Provider Get all APIs**: Simplifies the process of recieving the information of all available services published previously, +- **Invoker CAPIF connector offboarding**: Simplifies the process of offboarding for Invoker users, +- **Provider CAPIF connector offboarding**: Simplifies the process of offboarding for Provider users. + +[OPENCAPIF SDK CODE STRUCTURE] + + + + +## Other features + +Apart from the SDK core, there are available different functionalities for development purposes: + +- **Register and login**: Facilitates the logging process for admin users and creates a CAPIF user, +- **Deregister and login**: Facilitates the logging process for admin users and eliminates a CAPIF user. + + + + +# How to use OpenCAPIF SDK + +1 - First it is required to complete the utilities file with the absolute paths of target environment in order to complete the configuration of the SDK: +- NOTE register file is not needed for the use of the SDK, +- NOTE provider_exposer_get_sample_api_description_path is mandatory if publish functionalities are required. + +2 - Then it is needed to fill out config files depending on the features required to be used from the SDK. + +