docs/api-reference/bp-processor.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0
   2 .. International License. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright (C) 2020 Deutsche Telekom AG.
   4
   5 Blueprint Processor API Reference
   6 ==================================
   7
   8 Introduction
   9 --------------
  10
  11 This section shows all resources and endpoints which CDS BP processor currently provides through a swagger file
  12 which is automatically created during CDS build process by Swagger Maven Plugin. A corresponding Postman collection is
  13 also included. Endpoints can also be described using this template
  14 :download:`api-doc-template.rst <media/api-doc-template.txt>` but this is not the preferred way to describe the CDS API.
  15
  16 You can find a sample workflow tutorial :ref:`below <workflow-tutorial>` which will show how to use the endpoints
  17 in the right order. This will give you a better understanding of the CDS Blueprint Processor API.
  18
  19 Getting Started
  20 -----------------
  21
  22 If you cant access a running CDS Blueprint Processor yet, you can choose one of the below options to run it.
  23 Afterwards you can start trying out the API.
  24
  25 * CDS in Microk8s: https://wiki.onap.org/display/DW/Running+CDS+on+Microk8s (RDT link to be added)
  26 * CDS in Minikube: https://wiki.onap.org/display/DW/Running+CDS+in+minikube (RDT link to be added)
  27 * CDS in an IDE:  :ref:`Running BP Processor Microservice in an IDE <running_bp_processor_in_ide>`
  28
  29 Authorization
  30 -----------------
  31
  32 Use Basic authorization with `ccsdkapps` as a username and password, in Header ``Authorization: Basic Y2NzZGthcHBzOmNjc2RrYXBwcw==``.
  33
  34 Download
  35 ------------
  36
  37 Here is the automatically created swagger file for CDS Blueprint Processor API:
  38 :download:`cds-bp-processor-api-swagger.json <media/cds-bp-processor-api-swagger.json>`
  39
  40 You can find a postman collection including sample requests for all endpoints here:
  41 :download:`bp-processor.postman_collection.json <media/bp-processor.postman_collection.json>`.
  42 Please keep the Postman Collection up-to-date for new endpoints.
  43
  44 General Setup
  45 --------------
  46
  47 All endpoints are accessable under ``http://{{host}}:{{port}}/api/v1/``. Host and port depends on your CDS BP processor
  48 deployment.
  49
  50
  51 List all endpoints
  52 -------------------
  53
  54 Lists all available endpoints from blueprints processor API.
  55
  56
  57 Request
  58 ~~~~~~~~~~
  59
  60 GET ``http://{{host}}:{{port}}/actuator/mappings``
  61 ....................................................
  62
  63 Lists all endpoints from blueprints processor.
  64
  65 .. code-block:: bash
  66    :caption: **request**
  67
  68    curl --location --request GET 'http://localhost:8081/actuator/mappings' \
  69    --header 'Authorization: Basic Y2NzZGthcHBzOmNjc2RrYXBwcw=='
  70
  71
  72 Success Response
  73 ~~~~~~~~~~~~~~~~~
  74
  75 HTTP Status 202 OK
  76
  77 .. code-block:: json
  78    :caption: **sample response body**
  79
  80    {
  81       "contexts": {
  82          "application": {
  83                "mappings": {
  84                   "dispatcherHandlers": {
  85                      "webHandler": [
  86                            {
  87                               "predicate": "{GET /api/v1/blueprint-model, produces [application/json]}",
  88                               "handler": "org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController#allBlueprintModel()",
  89                               "details": {
  90                                  "handlerMethod": {
  91                                        "className": "org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController",
  92                                        "name": "allBlueprintModel",
  93                                        "descriptor": "()Ljava/util/List;"
  94                                  },
  95                                  "handlerFunction": null,
  96                                  "requestMappingConditions": {
  97                                        "consumes": [],
  98                                        "headers": [],
  99                                        "methods": [
 100                                           "GET"
 101                                        ],
 102                                        "params": [],
 103                                        "patterns": [
 104                                           "/api/v1/blueprint-model"
 105                                        ],
 106                                        "produces": [
 107                                           {
 108                                              "mediaType": "application/json",
 109                                              "negated": false
 110                                           }
 111                                        ]
 112                                  }
 113                               }
 114                            },
 115                            {
 116                               "predicate": "{GET /api/v1/blueprint-model/meta-data/{keyword}, produces [application/json]}",
 117                               "handler": "org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController#allBlueprintModelMetaData(String, Continuation)",
 118                               "details": {
 119                                  "handlerMethod": {
 120                                        "className": "org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController",
 121                                        "name": "allBlueprintModelMetaData",
 122                                        "descriptor": "(Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;"
 123                                  },
 124                                  "handlerFunction": null,
 125                                  "requestMappingConditions": {
 126                                        "consumes": [],
 127                                        "headers": [],
 128                                        "methods": [
 129                                           "GET"
 130                                        ],
 131                                        "params": [],
 132                                        "patterns": [
 133                                           "/api/v1/blueprint-model/meta-data/{keyword}"
 134                                        ],
 135                                        "produces": [
 136                                           {
 137                                              "mediaType": "application/json",
 138                                              "negated": false
 139                                           }
 140                                        ]
 141                                  }
 142                               }
 143                            }
 144                      ]
 145                   }
 146                },
 147                "parentId": null
 148          }
 149       }
 150    }
 151
 152
 153 API Reference
 154 --------------
 155
 156 .. warning::
 157    In the used Sphinx plugin `sphinxcontrib-swaggerdoc` some information of the swagger file is not
 158    rendered completely, e.g. the request body. Use your favorite Swagger Editor and paste the swagger file
 159    to get a complete view of the API reference, e.g. on https://editor.swagger.io/.
 160
 161 .. swaggerv2doc:: media/cds-bp-processor-api-swagger.json
 162
 163
 164
 165 .. _workflow-tutorial:
 166
 167 Workflow Tutorial
 168 ------------------
 169
 170 Introduction
 171 ~~~~~~~~~~~~~
 172
 173 This section will show a basic workflow how to proceed a CBA. For this we will follow
 174 the :ref:`PNF Simulator use case <pnf_simulator_use_case>` guide. We will use the same CBA but since this CBA is loaded during
 175 bootstrap per default we will first delete it and afterwards manually enrich and save it in CDS.
 176 The referred use case shows how the day-n configuration is assigned and deployed to a PNF through CDS.
 177 You don't necessarily need a netconf server (which will act as an PNF Simulator) running to get a understanding about
 178 this workflow tutorial. Just take care that without a set up netconf server the day-n configuration deployment will fail
 179 in the last step.
 180
 181 Use the Postman Collection from the referred use case to get sample requests for the following steps:
 182 :download:`json <../usecases/media/pnf-simulator.postman_collection.json>`.
 183
 184 The CBA which we are using is downloadable here :download:`zip <media/workflow-tutorial-cba.zip>`. Hint: this CBA is
 185 also included in the CDS source code for bootstrapping.
 186
 187 Set up CDS
 188 ~~~~~~~~~~
 189
 190 If not done before, run `Bootrap` request which will call Bootstrap API of CDS (``POST /api/v1/blueprint-model/bootstrap``)
 191 to load all the CDS default model artifacts into CDS. You should get HTTP status 200 for the below command.
 192
 193 Call `Get Blueprints` request to get all blueprint models which are saved in CDS. This will call the ``GET /api/v1/blueprint-model``
 194 endpoint. You will see the blueprint model ``"artifactName": "pnf_netconf"`` which is loaded by calling bootstrap since Guilin release.
 195 Since we manually want to load the CBA delete the desired CBA from CDS first through calling the delete endpoint
 196 ``DELETE /api/v1/blueprint-model/name/{name}/version/{version}``. If you call `Get Blueprints` again you can see that the
 197 ``pnf_netconf`` CBA is missing now.
 198
 199 Because the CBA contains a custom data dictionary we need to push the custom entries to CDS first through calling `Data Dictionary` request.
 200 Actually the custom entries are also already loaded through bootstrap but just pretend they are not present in CDS so far.
 201
 202 .. note::
 203    For every data dictionary entry CDS API needs to be called seperately. The postman collection contains a loop to
 204    go through all custom entries and call data dictionary endpoint seperately. To execute this loop,
 205    open `Runner` in Postman and run `Data Dictionary` request like it is shown in the picture below.
 206
 207    |imageDDPostmanRunner|
 208
 209
 210 Enrichment
 211 ~~~~~~~~~~~~
 212
 213 Enrich the blueprint through executing the `Enrich Blueprint` request. Take care to provide the CBA file which you
 214 can download here :download:`zip <media/workflow-tutorial-cba.zip>` in the request body. After the request got executed
 215 download the response body like shown in the picture below, this will be your enriched CBA file.
 216
 217 |saveResponseImage|
 218
 219
 220 Deploy/Save the Blueprint
 221 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 222
 223 Run `Save Blueprint` request to save/deploy the Blueprint into the CDS database. Take care to provide the enriched
 224 CBA file which you downloaded earlier in the request body.
 225
 226 After that you should see the new model ``"artifactName": "pnf_netconf"`` by calling `Get Blueprints` request.
 227
 228 An alternative would be to use ``POST /api/v1/blueprint-model/publish`` endpoint, which would also validate the CBA.
 229 For doing enrichment and saving the CBA in a single call ``POST /api/v1/blueprint-model/enrichandpublish`` could also be used.
 230
 231 Config-Assign / Config-Deploy
 232 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 233
 234 From now on you can continue with the :ref:`PNF Simulator use case <pnf_simulator_use_case_config_assign_deploy>` from section
 235 `Config-assign and config-deploy` to finish the workflow tutorial. The provided Postman collection already contains all
 236 the needed requests also for this part so you don't need to create the calls and payloads manually.
 237 Take care that the last step will fail if you don't have a netconf server set up.
 238
 239
 240 .. |imageDDPostmanRunner| image:: media/dd-postman-runner.png
 241    :width: 500pt
 242
 243 .. |saveResponseImage| image:: media/save-response-postman.png
 244    :width: 500pt