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 <api-doc-template.rst>` 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                            ...
  88
  89                            {
  90                               "predicate": "{GET /api/v1/blueprint-model, produces [application/json]}",
  91                               "handler": "org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController#allBlueprintModel()",
  92                               "details": {
  93                                  "handlerMethod": {
  94                                        "className": "org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController",
  95                                        "name": "allBlueprintModel",
  96                                        "descriptor": "()Ljava/util/List;"
  97                                  },
  98                                  "handlerFunction": null,
  99                                  "requestMappingConditions": {
 100                                        "consumes": [],
 101                                        "headers": [],
 102                                        "methods": [
 103                                           "GET"
 104                                        ],
 105                                        "params": [],
 106                                        "patterns": [
 107                                           "/api/v1/blueprint-model"
 108                                        ],
 109                                        "produces": [
 110                                           {
 111                                              "mediaType": "application/json",
 112                                              "negated": false
 113                                           }
 114                                        ]
 115                                  }
 116                               }
 117                            },
 118                            {
 119                               "predicate": "{GET /api/v1/blueprint-model/meta-data/{keyword}, produces [application/json]}",
 120                               "handler": "org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController#allBlueprintModelMetaData(String, Continuation)",
 121                               "details": {
 122                                  "handlerMethod": {
 123                                        "className": "org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController",
 124                                        "name": "allBlueprintModelMetaData",
 125                                        "descriptor": "(Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;"
 126                                  },
 127                                  "handlerFunction": null,
 128                                  "requestMappingConditions": {
 129                                        "consumes": [],
 130                                        "headers": [],
 131                                        "methods": [
 132                                           "GET"
 133                                        ],
 134                                        "params": [],
 135                                        "patterns": [
 136                                           "/api/v1/blueprint-model/meta-data/{keyword}"
 137                                        ],
 138                                        "produces": [
 139                                           {
 140                                              "mediaType": "application/json",
 141                                              "negated": false
 142                                           }
 143                                        ]
 144                                  }
 145                               }
 146                            }
 147
 148                            ...
 149
 150                      ]
 151                   }
 152                },
 153                "parentId": null
 154          }
 155       }
 156    }
 157
 158
 159 API Reference
 160 --------------
 161
 162 .. warning::
 163    In the used Sphinx plugin `sphinxcontrib-swaggerdoc` some information of the swagger file is not
 164    rendered completely, e.g. the request body. Use your favorite Swagger Editor and paste the swagger file
 165    to get a complete view of the API reference, e.g. on https://editor.swagger.io/.
 166
 167 .. swaggerv2doc:: media/cds-bp-processor-api-swagger.json
 168
 169
 170
 171 .. _workflow-tutorial:
 172
 173 Workflow Tutorial
 174 ------------------
 175
 176 Introduction
 177 ~~~~~~~~~~~~~
 178
 179 This section will show a basic workflow how to proceed a CBA. For this we will follow
 180 the :ref:`PNF Simulator use case <pnf_simulator_use_case>` guide. We will use the same CBA but since this CBA is loaded during
 181 bootstrap per default we will first delete it and afterwards manually enrich and save it in CDS.
 182 The referred use case shows how the day-n configuration is assigned and deployed to a PNF through CDS.
 183 You don't necessarily need a netconf server (which will act as an PNF Simulator) running to get a understanding about
 184 this workflow tutorial. Just take care that without a set up netconf server the day-n configuration deployment will fail
 185 in the last step.
 186
 187 Use the Postman Collection from the referred use case to get sample requests for the following steps:
 188 :download:`json <../usecases/media/pnf-simulator.postman_collection.json>`.
 189
 190 The CBA which we are using is downloadable here :download:`zip <media/workflow-tutorial-cba.zip>`. Hint: this CBA is
 191 also included in the CDS source code for bootstrapping.
 192
 193 Set up CDS
 194 ~~~~~~~~~~
 195
 196 If not done before, run `Bootrap` request which will call Bootstrap API of CDS (``POST /api/v1/blueprint-model/bootstrap``)
 197 to load all the CDS default model artifacts into CDS. You should get HTTP status 200 for the below command.
 198
 199 Call `Get Blueprints` request to get all blueprint models which are saved in CDS. This will call the ``GET /api/v1/blueprint-model``
 200 endpoint. You will see the blueprint model ``"artifactName": "pnf_netconf"`` which is loaded by calling bootstrap since Guilin release.
 201 Since we manually want to load the CBA delete the desired CBA from CDS first through calling the delete endpoint
 202 ``DELETE /api/v1/blueprint-model/name/{name}/version/{version}``. If you call `Get Blueprints` again you can see that the
 203 ``pnf_netconf`` CBA is missing now.
 204
 205 Because the CBA contains a custom data dictionary we need to push the custom entries to CDS first through calling `Data Dictionary` request.
 206 Actually the custom entries are also already loaded through bootstrap but just pretend they are not present in CDS so far.
 207
 208 .. note::
 209    For every data dictionary entry CDS API needs to be called seperately. The postman collection contains a loop to
 210    go through all custom entries and call data dictionary endpoint seperately. To execute this loop,
 211    open `Runner` in Postman and run `Data Dictionary` request like it is shown in the picture below.
 212
 213    |imageDDPostmanRunner|
 214
 215
 216 Enrichment
 217 ~~~~~~~~~~~~
 218
 219 Enrich the blueprint through executing the `Enrich Blueprint` request. Take care to provide the CBA file which you
 220 can download here :download:`zip <media/workflow-tutorial-cba.zip>` in the request body. After the request got executed
 221 download the response body like shown in the picture below, this will be your enriched CBA file.
 222
 223 |saveResponseImage|
 224
 225
 226 Deploy/Save the Blueprint
 227 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 228
 229 Run `Save Blueprint` request to save/deploy the Blueprint into the CDS database. Take care to provide the enriched
 230 CBA file which you downloaded earlier in the request body.
 231
 232 After that you should see the new model ``"artifactName": "pnf_netconf"`` by calling `Get Blueprints` request.
 233
 234 An alternative would be to use ``POST /api/v1/blueprint-model/publish`` endpoint, which would also validate the CBA.
 235 For doing enrichment and saving the CBA in a single call ``POST /api/v1/blueprint-model/enrichandpublish`` could also be used.
 236
 237 Config-Assign / Config-Deploy
 238 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 239
 240 From now on you can continue with the :ref:`PNF Simulator use case <pnf_simulator_use_case_config_assign_deploy>` from section
 241 `Config-assign and config-deploy` to finish the workflow tutorial. The provided Postman collection already contains all
 242 the needed requests also for this part so you don't need to create the calls and payloads manually.
 243 Take care that the last step will fail if you don't have a netconf server set up.
 244
 245
 246 .. |imageDDPostmanRunner| image:: media/dd-postman-runner.png
 247    :width: 500pt
 248
 249 .. |saveResponseImage| image:: media/save-response-postman.png
 250    :width: 500pt