Blueprint Processor API Reference

Introduction

This section shows all resources and endpoints which CDS BP processor currently provides through a swagger file which is automatically created during CDS build process by Swagger Maven Plugin. A corresponding Postman collection is also included. Endpoints can also be described using this template api-doc-template.rst but this is not the preferred way to describe the CDS API.

You can find a sample workflow tutorial below which will show how to use the endpoints in the right order. This will give you a better understanding of the CDS Blueprint Processor API.

Getting Started

If you cant access a running CDS Blueprint Processor yet, you can choose one of the below options to run it. Afterwards you can start trying out the API.

CDS in Microk8s: https://wiki.onap.org/display/DW/Running+CDS+on+Microk8s (RDT link to be added)
CDS in Minikube: https://wiki.onap.org/display/DW/Running+CDS+in+minikube (RDT link to be added)
CDS in an IDE: Running BP Processor Microservice in an IDE

Authorization

Use Basic authorization with ccsdkapps as a username and password, in Header Authorization: Basic Y2NzZGthcHBzOmNjc2RrYXBwcw==.

Download

Here is the automatically created swagger file for CDS Blueprint Processor API: cds-bp-processor-api-swagger.json

You can find a postman collection including sample requests for all endpoints here: bp-processor.postman_collection.json. Please keep the Postman Collection up-to-date for new endpoints.

General Setup

All endpoints are accessable under http://{{host}}:{{port}}/api/v1/. Host and port depends on your CDS BP processor deployment.

List all endpoints

Lists all available endpoints from blueprints processor API.

Request

GET `http://{{host}}:{{port}}/actuator/mappings`

Lists all endpoints from blueprints processor.

request

curl --location --request GET 'http://localhost:8081/actuator/mappings' \
--header 'Authorization: Basic Y2NzZGthcHBzOmNjc2RrYXBwcw=='

Success Response

HTTP Status 202 OK

sample response body

{
   "contexts": {
      "application": {
            "mappings": {
               "dispatcherHandlers": {
                  "webHandler": [

                        ...

                        {
                           "predicate": "{GET /api/v1/blueprint-model, produces [application/json]}",
                           "handler": "org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController#allBlueprintModel()",
                           "details": {
                              "handlerMethod": {
                                    "className": "org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController",
                                    "name": "allBlueprintModel",
                                    "descriptor": "()Ljava/util/List;"
                              },
                              "handlerFunction": null,
                              "requestMappingConditions": {
                                    "consumes": [],
                                    "headers": [],
                                    "methods": [
                                       "GET"
                                    ],
                                    "params": [],
                                    "patterns": [
                                       "/api/v1/blueprint-model"
                                    ],
                                    "produces": [
                                       {
                                          "mediaType": "application/json",
                                          "negated": false
                                       }
                                    ]
                              }
                           }
                        },
                        {
                           "predicate": "{GET /api/v1/blueprint-model/meta-data/{keyword}, produces [application/json]}",
                           "handler": "org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController#allBlueprintModelMetaData(String, Continuation)",
                           "details": {
                              "handlerMethod": {
                                    "className": "org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController",
                                    "name": "allBlueprintModelMetaData",
                                    "descriptor": "(Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;"
                              },
                              "handlerFunction": null,
                              "requestMappingConditions": {
                                    "consumes": [],
                                    "headers": [],
                                    "methods": [
                                       "GET"
                                    ],
                                    "params": [],
                                    "patterns": [
                                       "/api/v1/blueprint-model/meta-data/{keyword}"
                                    ],
                                    "produces": [
                                       {
                                          "mediaType": "application/json",
                                          "negated": false
                                       }
                                    ]
                              }
                           }
                        }

                        ...

                  ]
               }
            },
            "parentId": null
      }
   }
}

API Reference

Warning

In the used Sphinx plugin sphinxcontrib-swaggerdoc some information of the swagger file is not rendered completely, e.g. the request body. Use your favorite Swagger Editor and paste the swagger file to get a complete view of the API reference, e.g. on https://editor.swagger.io/.

Blueprint Model Catalog

GET /api/v1/blueprint-model

List all Blueprint Models

Description: Lists all meta-data of blueprint models which are saved in CDS.
Produces: [‘application/json’]

Responses

200 - OK

500 - Internal Server Error

POST /api/v1/blueprint-model

Save a Blueprint Model

Description: Saves a blueprint model by the given CBA zip file input. There is no validation of the attached CBA happening when this API is called.
Consumes: [‘multipart/form-data’]
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
file	body	CBA file to be uploaded (example: cba.zip)

Responses

200 - OK

500 - Internal Server Error

POST /api/v1/blueprint-model/bootstrap

Bootstrap CDS

Description: Loads all Model Types, Resource Dictionaries and Blueprint Models which are included in CDS by default. Before starting to work with CDS, bootstrap should be called to load all the basic models that each orginization might support. Parameter values can be set as `false` to skip loading e.g. the Resource Dictionaries but this is not recommended.
Consumes: [‘application/json’]
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
body	body	Specifies which elements to load

Responses

200 - OK

500 - Internal Server Error

GET /api/v1/blueprint-model/by-name/{name}/version/{version}

Get a Blueprint Model by Name and Version

Description: Get Meta-Data of a Blueprint Model by its name and version.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
name	path	Name of the blueprint model	string
version	path	Version of the blueprint model	string

Responses

200 - OK

404 - Not Found

GET /api/v1/blueprint-model/download/by-name/{name}/version/{version}

Download a Blueprint Model

Description: Gets the CBA of a blueprint model by its name and version. Response can be saved to a file to download the CBA.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
name	path	Name of the blueprint model	string
version	path	Version of the blueprint model	string

Responses

200 - OK

404 - Not Found

GET /api/v1/blueprint-model/download/{id}

Download a Blueprint Model by ID

Description: Gets the CBA of a blueprint model by its ID. Response can be saved to a file to download the CBA.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
id	path	ID of the blueprint model to download	string

Responses

200 - OK

404 - Not Found

POST /api/v1/blueprint-model/enrich

Enrich a Blueprint Model

Description: Enriches the attached CBA and returns the enriched CBA zip file in the response. The enrichment process will complete the package by providing all the definition of types used.
Consumes: [‘multipart/form-data’]
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
file	body	CBA zip file to be uploaded (example: cba_unenriched.zip)

Responses

200 - successful operation

POST /api/v1/blueprint-model/enrichandpublish

Enrich and publish a Blueprint Model

Description: Enriches the attached CBA, validates it and saves it in CDS if validation was successful.
Consumes: [‘multipart/form-data’]
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
file	body	Unenriched CBA zip file to be uploaded (example: cba_unenriched.zip)

Responses

200 - OK

503 - Service Unavailable

GET /api/v1/blueprint-model/meta-data/{keyword}

Search for Blueprints by a Keyword

Description: Lists all blueprint models by a matching keyword in any of the meta-data of the blueprint models. Blueprint models are just returned if a whole keyword is matching, not just parts of it. Not case-sensitive. Used by CDS UI.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
keyword	path	Keyword to search for in blueprint model meta-data	string

Responses

200 - successful operation

DELETE /api/v1/blueprint-model/name/{name}/version/{version}

Delete a Blueprint Model by Name

Description: Deletes a blueprint model identified by its name and version from CDS.

Parameters

Name	Position	Description	Type
name	path	Name of the blueprint model	string
version	path	Version of the blueprint model	string

Responses

200 - successful operation

GET /api/v1/blueprint-model/paged

Get Blueprints ordered

Description: Lists all blueprint models which are saved in CDS in an ordered mode.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
limit	query	Maximum number of returned blueprint models	integer
offset	query	Offset	integer
sort	query	Order of returned blueprint models	string
sortType	query	Ascend or descend ordering	string

Responses

200 - successful operation

GET /api/v1/blueprint-model/paged/meta-data/{keyword}

Search for Blueprints by a Keyword in an ordered mode

Description: Lists all blueprint models by a matching keyword in any of the meta-data of the blueprint models in an ordered mode. Blueprint models are just returned if a whole keyword is matching, not just parts of it. Not case-sensitive. Used by CDS UI.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
keyword	path	Keyword to search for in blueprint model meta-data	string
limit	query	Maximum number of returned blueprint models	integer
offset	query	Offset	integer
sort	query	Order of returned blueprint models	string
sortType	query	Ascend or descend ordering	string

Responses

200 - successful operation

POST /api/v1/blueprint-model/publish

Publish a Blueprint Model

Description: Validates the attached CBA file and saves it in CDS if validation was successful. CBA needs to be already enriched.
Consumes: [‘multipart/form-data’]
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
file	body	Enriched CBA zip file to be uploaded (example: cba_enriched.zip)

Responses

200 - successful operation

GET /api/v1/blueprint-model/search/{tags}

Search for a Blueprint by Tag

Description: Searches for all blueprint models which contain the specified input parameter in their tags. Blueprint models which contain just parts of the searched word in their tags are also returned.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
tags	path	Tag to search for	string

Responses

200 - successful operation

POST /api/v1/blueprint-model/workflow-spec

Get Workflow Specification

Description: Get the workflow of a blueprint identified by Blueprint and workflow name. Inputs, outputs and data types of workflow is returned.
Consumes: [‘application/json’]
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
body	body	Blueprint and workflow identification

Responses

200 - successful operation

GET /api/v1/blueprint-model/workflows/blueprint-name/{name}/version/{version}

Get Workflows of a Blueprint

Description: Get all available workflows of a Blueprint identified by its name and version.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
name	path	Name of the blueprint model	string
version	path	Version of the blueprint model	string

Responses

200 - successful operation

GET /api/v1/blueprint-model/{id}

Get a Blueprint Model by ID

Description: Get meta-data of a blueprint model by its internally created ID.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
id	path	ID of the blueprint model to search for	string

Responses

200 - OK

404 - Not Found

DELETE /api/v1/blueprint-model/{id}

Delete a Blueprint Model by ID

Description: Delete a blueprint model by its ID. ID is the internally created ID of blueprint, not the name of blueprint.

Parameters

Name	Position	Description	Type
id	path	ID of the blueprint model to delete	string

Responses

200 - OK

404 - RESOURCE_NOT_FOUND

Model Type Catalog

POST /api/v1/model-type/

Save a model type

Description: Save a model type by model type definition provided.
Consumes: [‘application/json’]
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
body	body

Responses

200 - successful operation

GET /api/v1/model-type/by-definition/{definitionType}

Retrieve a list of model types

Description: Retrieve a list of model types by definition type provided.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
definitionType	path		string

Responses

200 - successful operation

GET /api/v1/model-type/search/{tags}

Retrieve a list of model types

Description: Retrieve a list of model types by tags provided.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
tags	path		string

Responses

200 - successful operation

GET /api/v1/model-type/{name}

Retrieve a model type

Description: Retrieve a model type by name provided.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
name	path		string

Responses

200 - successful operation

DELETE /api/v1/model-type/{name}

Remove a model type

Description: Remove a model type by name provided.

Parameters

Name	Position	Description	Type
name	path		string

Responses

200 - successful operation

Resource configuration

GET /api/v1/configs

Retrieve a resource configuration snapshot

Description: Retrieve a config snapshot, identified by its Resource Id and Type. An extra ‘format’ parameter can be passed to tell what content-type is expected.
Produces: [‘text/plain’, ‘application/json’, ‘application/xml’]

Parameters

Name	Position	Description	Type
resourceType	query	Resource Type associated of the resource configuration snapshot	string
resourceId	query	Resource Id associated of the resource configuration snapshot	string
status	query	Status of the snapshot being retrieved	string
format	query	Expected format of the snapshot being retrieved	string

Responses

200 - successful operation

GET /api/v1/configs/allByID

Retrieve all resource configuration snapshots identified by a given resource_id

Description: Retrieve all config snapshots, identified by its Resource Id, ordered by most recently created/modified date.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
resourceId	query	Resource Id associated of the resource configuration snapshots	string
status	query	Status of the snapshot being retrieved	string

Responses

200 - successful operation

GET /api/v1/configs/allByType

Retrieve all resource configuration snapshots for a given resource type

Description: Retrieve all config snapshots matching a specified Resource Type, ordered by most recently created/modified date.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
resourceType	query	Resource Type associated of the resource configuration snapshot	string
status	query	Status of the snapshot being retrieved	string

Responses

200 - successful operation

POST /api/v1/configs/{resourceType}/{resourceId}/{status}

Store a resource configuration snapshot identified by resourceId, resourceType, status

Description: Store a resource configuration snapshot, identified by its resourceId and resourceType, and optionally its status, either RUNNING or CANDIDATE.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
resourceType	path	Resource Type associated with the resolution	string
resourceId	path	Resource Id associated with the resolution	string
status	path	Status of the snapshot being retrieved	string
body	body	Config snapshot to store

Responses

200 - successful operation

DELETE /api/v1/configs/{resourceType}/{resourceId}/{status}

Delete a resource configuration snapshot identified by resourceId, resourceType, status.

Description: Delete a resource configuration snapshot, identified by its resourceId and resourceType, and optionally its status, either RUNNING or CANDIDATE.

Parameters

Name	Position	Description	Type
resourceType	path	Resource Type associated with the resolution.	string
resourceId	path	Resource Id associated with the resolution.	string
status	path	Status of the snapshot being deleted.	string

Responses

200 - successful operation

Resource dictionary

POST /api/v1/dictionary

Save a resource dictionary

Description: Save a resource dictionary by dictionary provided.
Consumes: [‘application/json’]
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
body	body	Resource dictionary to store

Responses

200 - successful operation

POST /api/v1/dictionary/by-names

Search for a resource dictionary

Description: Search for a resource dictionary by names provided.
Consumes: [‘application/json’]
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
body	body	List of names

Responses

200 - successful operation

POST /api/v1/dictionary/definition

Save a resource dictionary

Description: Save a resource dictionary by resource definition provided.
Consumes: [‘application/json’]
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
body	body	Resource definition to generate

Responses

200 - successful operation

GET /api/v1/dictionary/resource_dictionary_group

Retrieve all resource dictionary groups

Description: Retrieve all resource dictionary groups.
Produces: [‘application/json’]

Responses

200 - successful operation

GET /api/v1/dictionary/search/{tags}

Search for a resource dictionary

Description: Search for a resource dictionary by tags provided.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
tags	path	Tags list	string

Responses

200 - successful operation

GET /api/v1/dictionary/source-mapping

Search for a source mapping

Description: Search for a source mapping.
Produces: [‘application/json’]

Responses

200 - successful operation

GET /api/v1/dictionary/{name}

Retrieve a resource dictionary

Description: Retrieve a resource dictionary by name provided.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
name	path	Name of the resource	string

Responses

200 - successful operation

DELETE /api/v1/dictionary/{name}

Remove a resource dictionary

Description: Remove a resource dictionary by name provided.

Parameters

Name	Position	Description	Type
name	path	Name of the resource	string

Responses

200 - successful operation

Resource template

POST /api/v1/template/{bpName}/{bpVersion}/{artifactName}/{resolutionKey}

Store a resolved template w/ resolution-key

Description: Store a template for a given CBA’s action, identified by its blueprint name, blueprint version, artifact name and resolution key.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
bpName	path	Name of the CBA	string
bpVersion	path	Version of the CBA	string
artifactName	path	Artifact name for which to retrieve a resolved resource	string
resolutionKey	path	Resolution Key associated with the resolution	string
body	body	Template to store

Responses

200 - successful operation

POST /api/v1/template/{bpName}/{bpVersion}/{artifactName}/{resourceType}/{resourceId}

Store a resolved template w/ resourceId and resourceType

Description: Store a template for a given CBA’s action, identified by its blueprint name, blueprint version, artifact name, resourceId and resourceType.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
bpName	path	Name of the CBA	string
bpVersion	path	Version of the CBA	string
artifactName	path	Artifact name for which to retrieve a resolved resource	string
resourceType	path	Resource Type associated with the resolution	string
resourceId	path	Resource Id associated with the resolution	string
body	body	Template to store

Responses

200 - successful operation

Resources

GET /api/v1/resources

Get all resolved resources using the resolution key

Description: Retrieve all stored resolved resources using the blueprint name, blueprint version, artifact name and the resolution-key.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
bpName	query	Name of the CBA	string
bpVersion	query	Version of the CBA	string
artifactName	query	Artifact name for which to retrieve a resolved resource	string
resolutionKey	query	Resolution Key associated with the resolution	string
resourceType	query	Resource Type associated with the resolution	string
resourceId	query	Resource Id associated with the resolution	string

Responses

200 - successful operation

DELETE /api/v1/resources

Delete resources using resolution key

Description: Delete all the resources associated to a resolution-key using blueprint metadata, artifact name and the resolution-key.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
bpName	query	Name of the CBA	string
bpVersion	query	Version of the CBA	string
artifactName	query	Artifact name for which to retrieve a resolved resource	string
resolutionKey	query	Resolution Key associated with the resolution	string

Responses

200 - successful operation

GET /api/v1/resources/resource

Fetch a resource value using resolution key

Description: Retrieve a stored resource value using the blueprint metadata, artifact name, resolution-key along with the name of the resource value to retrieve.
Produces: [‘application/json’]

Parameters

Name	Position	Description	Type
bpName	query	Name of the CBA	string
bpVersion	query	Version of the CBA	string
artifactName	query	Artifact name for which to retrieve a resolved resource	string
resolutionKey	query	Resolution Key associated with the resolution	string
name	query	Name of the resource to retrieve	string

Responses

200 - successful operation

Workflow Tutorial

Introduction

This section will show a basic workflow how to proceed a CBA. For this we will follow the PNF Simulator use case guide. We will use the same CBA but since this CBA is loaded during bootstrap per default we will first delete it and afterwards manually enrich and save it in CDS. The referred use case shows how the day-n configuration is assigned and deployed to a PNF through CDS. You don’t necessarily need a netconf server (which will act as an PNF Simulator) running to get a understanding about this workflow tutorial. Just take care that without a set up netconf server the day-n configuration deployment will fail in the last step.

Use the Postman Collection from the referred use case to get sample requests for the following steps: json.

The CBA which we are using is downloadable here zip. Hint: this CBA is also included in the CDS source code for bootstrapping.

Set up CDS

If not done before, run Bootrap request which will call Bootstrap API of CDS (POST /api/v1/blueprint-model/bootstrap) to load all the CDS default model artifacts into CDS. You should get HTTP status 200 for the below command.

Call Get Blueprints request to get all blueprint models which are saved in CDS. This will call the GET /api/v1/blueprint-model endpoint. You will see the blueprint model "artifactName": "pnf_netconf" which is loaded by calling bootstrap since Guilin release. Since we manually want to load the CBA delete the desired CBA from CDS first through calling the delete endpoint DELETE /api/v1/blueprint-model/name/{name}/version/{version}. If you call Get Blueprints again you can see that the pnf_netconf CBA is missing now.

Because the CBA contains a custom data dictionary we need to push the custom entries to CDS first through calling Data Dictionary request. Actually the custom entries are also already loaded through bootstrap but just pretend they are not present in CDS so far.

Note

For every data dictionary entry CDS API needs to be called seperately. The postman collection contains a loop to go through all custom entries and call data dictionary endpoint seperately. To execute this loop, open Runner in Postman and run Data Dictionary request like it is shown in the picture below.

Enrichment

Enrich the blueprint through executing the Enrich Blueprint request. Take care to provide the CBA file which you can download here zip in the request body. After the request got executed download the response body like shown in the picture below, this will be your enriched CBA file.

Deploy/Save the Blueprint

Run Save Blueprint request to save/deploy the Blueprint into the CDS database. Take care to provide the enriched CBA file which you downloaded earlier in the request body.

After that you should see the new model "artifactName": "pnf_netconf" by calling Get Blueprints request.

An alternative would be to use POST /api/v1/blueprint-model/publish endpoint, which would also validate the CBA. For doing enrichment and saving the CBA in a single call POST /api/v1/blueprint-model/enrichandpublish could also be used.

Config-Assign / Config-Deploy

From now on you can continue with the PNF Simulator use case from section Config-assign and config-deploy to finish the workflow tutorial. The provided Postman collection already contains all the needed requests also for this part so you don’t need to create the calls and payloads manually. Take care that the last step will fail if you don’t have a netconf server set up.

Blueprint Processor API Reference

Introduction

Getting Started

Authorization

Download

General Setup

List all endpoints

Request

GET http://{{host}}:{{port}}/actuator/mappings

Success Response

API Reference

Blueprint Model Catalog

Model Type Catalog

Resource configuration

Resource dictionary

Resource template

Resources

Workflow Tutorial

Introduction

Set up CDS

Enrichment

Deploy/Save the Blueprint

Config-Assign / Config-Deploy

GET `http://{{host}}:{{port}}/actuator/mappings`