Commit 2c6572c3 authored by Jorge Moratinos's avatar Jorge Moratinos
Browse files

Merge branch 'OCF-Doc20-create-section-of-sdk-in-documentation' into 'develop' 

Resolve "Create section of SDK in documentation"

Closes #20

See merge request !24
parents 5669454d 22f2bc67

doc/example-clients/example-clients.md

0 → 100644
+6 −0
Original line number Diff line number Diff line 
# Invoker and Provider CLI



Check [Example Clients](https://labs.etsi.org/rep/ocf/example-clients) for further information.



[OCF Web]: https://ocf.etsi.org/ "OCF Web"

[OCF Documentation]: https://ocf.etsi.org/documentation/ "OCF Documentation"

doc/releasenotes.md

+104 −30
Original line number Diff line number Diff line
@@ -2,41 +2,76 @@ 


### **New Features**



#### 3GPP CAPIF release 18

#### **Upgrade code to 3GPP CAPIF release 18**



- New endpoints included in new release 18 with new logic.

- New logic to support ***Vendor Extensibility*** on Publish Service.

- New logic to support ***API Status*** feature on Publish and Events Services.

- Supported Features now are mandatory for all POST and PUT Requests as is described on TS 29.222.

    - **Possible Breaking change**, all POST request now must include supported features attribute, default can me set to "0" to keep all features inactive.

    - **Possible Breaking change** on Events API, if you need eventDetails information on notification you must activate **Enhanced Event Report** feature by setting properly the supported features flag.

- Supported Features now are mandatory for all POST and PUT Requests as is described on TS 29.222. To keep in mind:

    - All POST/PUT request now must include ***Supported Features*** attribute, default can me set to ``0`` to keep all features inactive.

    - On subscription to Event, if you need ***eventDetails*** information on notification you must activate ***Enhanced Event Report*** feature by setting properly the ***Supported Features*** flag.

- Detailed information about models and endpoints upgrade on [Upgrade Release 17 to 18 Wiki]



### **Technical Debt Solved**

#### **Vendor Extensibility**



#### **Api Status feature**

- Publish API:

    - On publishing a service API, **SupportedFeatures** is read and checked whether VendExt feature is enabled.

    - When VendExt is enabled, vendor-specific fields are searched and stored in the db inside the ServiceAPIDescription object

    - Vendor-specific fields are added according to the specific format:



- Events API:

    - Event internal notifications between services improved to accomplish specification.

    - On event subscription **SupportedFeatures** is readed and stored in db to accomplish specification.

    - Also **SupportedFeatures** is checked before send event notification, in order to accomplish specification, sending **eventDetails** and related information according to ***enhanced_event_report*** and ***apiStatusMonitoring*** supported features activated.

```json



#### **Issues**

    "vendorSpecific-urn:<organization>:<field name>": {

        "key1": "value1",

        ...

        "keyN": "valueN",

    }

  

- Solved issue to get ready REDIS on deployment: REDIS scheduled on start to allow receive notification since service is deployed.

- Solved problem removing service APIs published is provider register more than one APF.

- Solved Superadmin problem deleting service API published through helper service if provider is not present.

- Increased the overall stability, fixing some corner cases.

- Location headers now are filled in same way at all services that needs it.

- Security issues solved.

- Base docker images present on ETSI registry.

- Robot image uploaded to ETSI Registry.

    e.g. 

    "vendorSpecific-urn:etsi:mec:capifext:transport-info": {

        "name": "trasport1",

        "description": "Transport Info 1",

        "type": "REST_HTTP",

        "protocol": "HTTP",

        "version": "2",

        "security": {

            "grantTypes": "OAUTH2_CLIENT_CREDENTIALS",

            "tokenEndpoint": "https://token-endpoint/"

        }

    }

  

#### Local Scripts

    where organization is "etsi:mec" and field name "capifext:transport-info"



- All scripts were reviewed and improved.

- New scripts to manage users on local deployment added:

  - create_users.sh: helps developer to create new users in local deployment.

  - remove_users.sh: helps developer to remove users from db in local deployment.

```



- Discover API:

    - On Discover request **SupportedFeatures** is read and checked whether VendSpecQueryParams feature is enabled.

    - When VendSpecQueryParams is enabled, vendor-specific query parameters are parsed

    - Vendor specific query parameters are added on the GET request according to the following format:



```json

    https://{{CAPIF_HOSTNAME}}:{{CAPIF_PORT}}/{{DISCOVER_URL}}?

           ...

           vend-spec-<query parameter name>={

              "target": <string that contains the JSON pointer to the attribute in the resource representation>, 

              "value": <query parameter value>

    }

  

    e.g. 

    https://{{CAPIF_HOSTNAME}}:{{CAPIF_PORT}}/{{DISCOVER_URL}}?

           ...

           vend-spec-type={

              "target": "/vendorSpecific-urn:etsi:mec:capifext:transport-info", 

              "value": "REST_HTTP"

    }

```





#### **Api Status feature**



- New logic to support ***API Status*** feature on Publish and Events Services.

- Events API:

    - Event internal notifications between services improved to accomplish specification.

    - On event subscription **SupportedFeatures** is read and stored in db to accomplish specification.

    - Also **SupportedFeatures** is checked before send event notification, in order to accomplish specification, sending **eventDetails** and related information according to ***enhanced_event_report*** and ***apiStatusMonitoring*** supported features activated.



#### Remote Scripts
@@ -68,16 +103,55 @@ New scripts developed to help on remote deployment, configuration and testing. A 
    - ***populate_create_remote_dummy_users.sh***: : Create Dummy providers and invokers, publish service APIs and creates security context for invokers.

    - ***populate_remove_remote_dummy_users.sh***: Remove dummy information created.



### New Tools and Components



### **Documentation**

#### SDK



New Python SDK is developed in order to simplify the creation and operation of providers and invokers. Please check the [SDK repository](https://labs.etsi.org/rep/ocf/sdk) for more information, there you can get more information about how to use it and also how to contibute to it.



#### Provider and Invoker example Clients



In order to help developers to create their own invokers/providers entities and try the behavior of the OpenCAPIF, we also add to the OCF respository two example with console interaction at [example clients repository](https://labs.etsi.org/rep/ocf/example-clients):



#### New test included on documentation

- [invoker-cli](https://labs.etsi.org/rep/ocf/example-clients/invoker-cli)

- [provider-cli](https://labs.etsi.org/rep/ocf/example-clients/provider-cli)



More information on README of each component.



### **Testing**



- New Vendor Extensibility test suite with 9 tests. [Api Events Service](./testing/testplan/vendor_extensibility/README.md)

- New [API Status feature](./testing/testplan/api_status/README.md) test suite.

- New [API Status feature](./testing/testplan/api_status/README.md) test suite with 20 tests.

- Improved [Events test suite](./testing/testplan/api_events_service/README.md) with 8 new tests.

- Test plan updated with default supported features for all request set to "0" (all inactive by default) [See common operations](./testing/testplan/common_operations/README.md).



### **Technical Debt Solved**



#### Local Scripts



- All scripts were reviewed and improved.

- New scripts to manage users on local deployment added:

    - ***create_users.sh***: This script create users setup by parameters in local deployment.. Those users are created by administrator.

    - ***remove_users.sh***: This script removes user in local deployment.



#### **Issues**



- Solved issue to get ready REDIS on deployment: REDIS scheduled on start to allow receive notification since service is deployed.

- Solved problem removing service APIs published is provider register more than one APF.

- Solved Superadmin problem deleting service API published through helper service if provider is not present.

- Increased the overall stability, fixing some corner cases.

- Location headers now are filled in same way at all services that needs it.

- Security issues solved.

- Base docker images present on ETSI registry.

- Robot image uploaded to ETSI Registry.



### **Documentation**



- [Postman examples](./testing/postman/README.md) are updated, including flows.

- New tests are detailed descripted on [Test plan section](./testing/testplan/README.md)

- New [Contribute section](./contribute/).

- New [SDK Section](./sdk/sdk.md)



---



## **Release 1.0.0**
@@ -262,4 +336,4 @@ This Release also includes a Robot Test Suite for all those services and a Postm 
[OCF Registration Flow]: https://ocf.etsi.org/documentation/latest/testing/testplan/common_operations/ "OCF Registration Flow"

[New Registration Demo]: https://www.youtube.com/watch?v=sn-tN6eRvv8 "New Registration Demo"

[CICD Wiki]: https://labs.etsi.org/rep/ocf/community/-/wikis/OCF-CICD "CI/CD Wiki"

[Upgrade Release 17 to 18 Wiki]: https://labs.etsi.org/rep/ocf/community/-/wikis/?¿?¿?¿?¿?   "Upgrade Release 17 to 18 Wiki"
 
[Upgrade Release 17 to 18 Wiki]: https://labs.etsi.org/rep/ocf/community/-/wikis/3GPP-Release-18-upgrade   "Upgrade Release 17 to 18 Wiki"

doc/sdk/sdk.md

0 → 100644
+6 −0
Original line number Diff line number Diff line 
# SDK



Check [SDK repository](https://labs.etsi.org/rep/ocf/sdk) for further information.



[OCF Web]: https://ocf.etsi.org/ "OCF Web"

[OCF Documentation]: https://ocf.etsi.org/documentation/ "OCF Documentation"

mkdocs.yml

+4 −0
Original line number Diff line number Diff line
@@ -78,6 +78,10 @@ nav: 
      - Architecture: architecture.md

  - Getting Started:

      - How to Run: ./gettingstarted/howtorun.md

  - SDK:

      - Introduction: ./sdk/sdk.md

  - Example Clients:

      - Introduction: ./example-clients/example-clients.md

  - Testing:

      - Test Plan: ./testing/testplan/README.md

      - Robot Framework: ./testing/robotframework/README.md