Doc upgrade v2 (#2)

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

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

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

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

 4. [Network App developer path](#network-app-developer-path)

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

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

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

 4. [OpenCAPIF SDK requirements](#opencapif-sdk-requirements)

 5. [OpenCAPIF SDK Configuration](./doc/sdk_configuration.md)

 6. [**OpenCAPIF SDK full documentation**](./doc/sdk_full_documentation.md)

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

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

 6. [Network App developer path](#network-app-developer-path)

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

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

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

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

 7. [**OpenCAPIF SDK full documentation**](./doc/sdk_full_documentation.md)

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

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

# Repository structure

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

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

## OpenCAPIF SDK requirements

To leverage the OpenCAPIF SDK, it must have a registered user in the target CAPIF instance. **Please contact the administrator to obtain the necessary predefined credentials (username and password).**

To utilize the OpenCAPIF SDK, a registered user account within the target CAPIF instance is required. 

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

# Network App developer path

  provider.publish_services()

```

Code is next explained step by step:

1. **Create a Provider object:** \

   Initialize the provider by creating an instance of the `capif_provider_connector` class, passing the required [configuration](./doc/sdk_configuration.md) file:

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

  service_discoverer.get_tokens()

```

Code is explained next step by step:

Code is next explained step by step:

1. **Create an Invoker object:** \

   Initialize the invoker by creating an instance of the `capif_invoker_connector` class, passing the required [configuration](./doc/sdk_configuration.md) file.

      This alert is expected because the SDK tries to update the security context first. If a 404 error is received, it means the security context is not created yet, so the next step for the SDK is to register a new security service. 

5. **Retrieve security tokens:** \

  Use the get_tokens() method to obtain the necessary tokens for authenticating API requests.

  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.

    environment_id = "your-environment-id-must-be-here"

```

Now, in the next steps is going to be illustrated the usual flow of an Invoker that wants to use obtain the access token to use an API service:

1. **Create an Invoker object:** \

   Initialize the invoker by creating an instance of the `capif_invoker_connector` class, passing the required [configuration](./doc/sdk_configuration.md) file:

   Make sure that the configuration file is filled before creating the instance.

2. **Onboard the Invoker**: \

   Register the invoker with the CAPIF system to enable access to APIs:

   In this phase, the SDK creates and stores all the necessary files for using CAPIF as a invoker, such as the authorization certificate and the server certificate .Furthermore,it creates a file named `capif_api_security_context_details.json` , which stores important information about the invoker.

3.	**Create a Service Discoverer object:** \

  Initialize the service discovery mechanism to search for available services

4.	**Discover available services:** \

   Use the `discover()` method to retrieve a list of available APIs.\

   **DISCLAIMER:** If it's the first time the user runs `discover()`, it will show a warning alert like this:

        **WARNING** - Received 404 error, redirecting to register security service

      This alert is expected because the SDK tries to update the security context first. If a 404 error is received, it means the security context is not created yet, so the SDK's next step is to register a new security service. 

    In this phase, the SDK will find all the available APIs for the invoker.Consequently,it will save the most important information and will store it within the `capif_api_security_context_details.json`.

5.	**Retrieve security tokens:** \

  Use the get_tokens() method to obtain the necessary tokens for authenticating API requests: 

```python

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

  invoker.onboard_invoker()

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

  service_discoverer.discover()

  invoker.get_tokens()

```

Then all information,including the access_token for using the available APIs, will be at `capif_api_security_context_details.json` file

This file would be placed in the invoker_folder path, more specifically in the folder that corresponds of the capif_username used in the config_file.

Here is a sample of this capif_api_security_context_details [file](./samples/capif_api_security_context_details_sample.json) 

This image highlights Invoker path using SDK code:

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

### Important information for Invoker consumer

In the `invoker_folder`, it will be located several folders with each `capif_username` it has been onboarded as a provider. For each folder, it will be found:

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

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

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