diff options
| -rw-r--r-- | docs/api-reference/api-doc-template.rst | 205 | ||||
| -rw-r--r-- | docs/api-reference/bp-processor.rst | 216 | ||||
| -rw-r--r-- | docs/api-reference/index.rst | 12 | ||||
| -rw-r--r-- | docs/api-reference/media/bp-processor.postman_collection.json | 220 | ||||
| -rw-r--r-- | docs/index.rst | 9 |
5 files changed, 662 insertions, 0 deletions
diff --git a/docs/api-reference/api-doc-template.rst b/docs/api-reference/api-doc-template.rst new file mode 100644 index 000000000..54e587fd6 --- /dev/null +++ b/docs/api-reference/api-doc-template.rst @@ -0,0 +1,205 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2020 Deutsche Telekom AG. + + +.. This is a template to document new APIs for CDS blueprint processor + +.. make use of tabs whenever it fits + +Module +==================== + +Resource 1 +------------ + +General description about the resource. + + +Method 1 Endpoint 1 +~~~~~~~~~~~~~~~~~~~~ + +<method> ``<path>`` +...................... + +Method 1 Endpoint 1 description + +Request +........... + +.. code-block:: curl + :caption: **(sample) request** + + request command + +.. can be split into Header and Body description if thats more suitable. +.. If its split, Header requires content-type definition, Body requires example payload + +**Request Path Parameters:** + +.. list-table:: + :widths: 20 20 20 40 + :header-rows: 1 + + * - Parameter + - Type + - Required + - Description + * - value 1 + - value 2 + - value 3 + - value 4 + * - value 1 + - value 2 + - value 3 + - value 4 + +**Request Query Parameters:** + +.. list-table:: + :widths: 20 20 20 40 + :header-rows: 1 + + * - Parameter + - Type + - Required + - Description + * - value 1 + - value 2 + - value 3 + - value 4 + * - value 1 + - value 2 + - value 3 + - value 4 + +**Request Body Parameters:** + +.. list-table:: + :widths: 20 20 20 40 + :header-rows: 1 + + * - Parameter + - Type + - Required + - Description + * - value 1 + - value 2 + - value 3 + - value 4 + * - value 1 + - value 2 + - value 3 + - value 4 + +Success Response(s) +...................... + +HTTP Status 202 OK + +Headers: +``Content-Type:application/json`` + +.. code-block:: json + :caption: **(sample) response body and/or response schema** + + (sample) response (can be {}) + +**Success Response Parameters:** + +.. list-table:: + :widths: 30 30 40 + :header-rows: 1 + + * - Parameter + - Type + - Description + * - value 1 + - value 2 + - value 3 + * - value 1 + - value 2 + - value 3 + +Error Response(s) +...................... + +HTTP Status 404 The requested resource could not be found + +.. code-block:: json + :caption: **sample error response** + + error response + +**Error Response Parameters:** + +.. list-table:: + :widths: 30 30 40 + :header-rows: 1 + + * - Parameter + - Type + - Description + * - value 1 + - value 2 + - value 3 + * - value 1 + - value 2 + - value 3 + +.. or just table for responses with HTTP code, description and schema + +Consumes +............ + +``application/json`` + +Produces +........... + +``application/json`` + + +Functional Description +.............................. + +What does the API do in detail? + +Technical Description +........................... + +Called class, methods, other hints. + +Related topics +...................... + + * Topic 1 + * Topic 2 + + +Method 2 Endpoint 1 +~~~~~~~~~~~~~~~~~~~~ + +<method> ``<path>`` +...................... + +Method 2 Endpoint 1 description + +.. + + +Method 1 Endpoint 2 (Subresource): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +<method> ``<path><subpath>`` +.............................. + + +.. + +Resource 2 +-------------------- + + +.. + diff --git a/docs/api-reference/bp-processor.rst b/docs/api-reference/bp-processor.rst new file mode 100644 index 000000000..1498d13d6 --- /dev/null +++ b/docs/api-reference/bp-processor.rst @@ -0,0 +1,216 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2020 Deutsche Telekom AG. + +Blueprint Processor API Reference +================================== + +Introduction +-------------- + +This section shows all resources and endpoints which CDS BP processor currently provides with sample requests/responses, +parameter description and other information. If there is a new API and you want do document it, you can use this template +:download:`rst <api-doc-template.rst>`. + +Authentification +----------------- + +Use Basic athentification with `ccsdkapps` as a username and password, in Header ``Authorization: Basic Y2NzZGthcHBzOmNjc2RrYXBwcw==``. + +Download +------------ + +You can find a postman collection including sample requests here: :download:`JSON <media/bp-processor.postman_collection.json>` + +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. + +.. code-block:: curl + :caption: **request** + + curl --location --request GET 'http://localhost:8081/actuator/mappings' \ + --header 'Authorization: Basic Y2NzZGthcHBzOmNjc2RrYXBwcw==' + + +Success Response +~~~~~~~~~~~~~~~~~ + +HTTP Status 202 OK + +.. code-block:: json + :caption: **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 + } + } + } + +Blueprint Model Catalog API +---------------------------- + +Blueprint-model resource contains all Controller Blueprints Archive (CBA) packages which are available in CDS. +With blueprint-model API you can manage your CBAs. + + +List all blueprint models +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +GET ``/blueprint-model`` +.............................. + +Lists all blueprint models which are saved in CDS. + +Request +........... + +.. code-block:: curl + :caption: **request** + + curl --location --request GET 'http://{{ip_adress}}:{{port}}/api/v1/blueprint-model' \ + --header 'Authorization: Basic Y2NzZGthcHBzOmNjc2RrYXBwcw==' + +Produces +........... + +``application/json`` + + +Success Response +...................... + +HTTP Status 200 OK + +.. code-block:: json + :caption: **example response** + + [ + { + "blueprintModel": { + "id": "109e725d-5145-4f70-a2e7-ee6640e2fb5f", + "artifactUUId": null, + "artifactType": "SDNC_MODEL", + "artifactVersion": "1.0.0", + "artifactDescription": "", + "internalVersion": null, + "createdDate": "2020-11-09T19:00:20.000Z", + "artifactName": "vLB_CDS_RESTCONF", + "published": "Y", + "updatedBy": "DanielEmmarts>", + "tags": "vLB-CDS" + } + }, + { + "blueprintModel": { + "id": "5cce3804-09eb-473d-b513-81f8547a7240", + "artifactUUId": null, + "artifactType": "SDNC_MODEL", + "artifactVersion": "1.0.0", + "artifactDescription": "", + "internalVersion": null, + "createdDate": "2020-11-09T19:00:20.000Z", + "artifactName": "vLB_CDS", + "published": "Y", + "updatedBy": "TomKennedy>", + "tags": "vLB_CDS" + } + } + ] + +Technical Description +........................... + +Loads all Blueprint Models which are saved in the CDS database in table `BLUEPRINT_MODEL`. Unpublished and unproceeded +Blueprint Models are also included. +Called class/method: ``org.onap.ccsdk.cds.blueprintsprocessor.designer.api.BlueprintModelController#allBlueprintModel()``. diff --git a/docs/api-reference/index.rst b/docs/api-reference/index.rst new file mode 100644 index 000000000..64e330dce --- /dev/null +++ b/docs/api-reference/index.rst @@ -0,0 +1,12 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2020 Deutsche Telekom AG. + +Offered APIs +~~~~~~~~~~~~~~ + +.. toctree:: + :caption: Offered APIs + :maxdepth: 2 + + bp-processor
\ No newline at end of file diff --git a/docs/api-reference/media/bp-processor.postman_collection.json b/docs/api-reference/media/bp-processor.postman_collection.json new file mode 100644 index 000000000..4dd1c5fe5 --- /dev/null +++ b/docs/api-reference/media/bp-processor.postman_collection.json @@ -0,0 +1,220 @@ +{ + "info": { + "_postman_id": "481808a1-8f9d-47b3-8e03-9302d22731d9", + "name": "Blueprints Processor API Reference Collection", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" + }, + "item": [ + { + "name": "Get All Endpoints", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "" + }, + "description": "Lists all endpoints from blueprints processor" + }, + "response": [] + }, + { + "name": "Get Blueprints", + "protocolProfileBehavior": { + "disableBodyPruning": true + }, + "request": { + "auth": { + "type": "basic", + "basic": [ + { + "key": "password", + "value": "ccsdkapps", + "type": "string" + }, + { + "key": "username", + "value": "ccsdkapps", + "type": "string" + } + ] + }, + "method": "GET", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "", + "value": "", + "type": "text", + "disabled": true + } + ], + "body": { + "mode": "raw", + "raw": "{\r\n\"loadModelType\" : true,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}", + "options": { + "raw": {} + } + }, + "url": { + "raw": "http://{{host}}:{{port}}/api/v1/blueprint-model", + "protocol": "http", + "host": [ + "{{host}}" + ], + "port": "{{port}}", + "path": [ + "api", + "v1", + "blueprint-model" + ] + } + }, + "response": [ + { + "name": "CDS Bootstrap", + "originalRequest": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "", + "value": "", + "type": "text", + "disabled": true + } + ], + "body": { + "mode": "raw", + "raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}", + "options": { + "raw": {} + } + }, + "url": { + "raw": "http://localhost:8081/api/v1/blueprint-model/bootstrap", + "protocol": "http", + "host": [ + "localhost" + ], + "port": "8081", + "path": [ + "api", + "v1", + "blueprint-model", + "bootstrap" + ] + } + }, + "status": "OK", + "code": 200, + "_postman_previewlanguage": "json", + "header": [ + { + "key": "X-ONAP-RequestID", + "value": "b73253b6-d2be-4701-bdb2-31fa66b79a01" + }, + { + "key": "X-ONAP-InvocationID", + "value": "b1a59296-fcf2-4435-b8de-9a2e9b9f4077" + }, + { + "key": "X-ONAP-PartnerName", + "value": "cds-controller" + }, + { + "key": "Vary", + "value": "Origin" + }, + { + "key": "Vary", + "value": "Access-Control-Request-Method" + }, + { + "key": "Vary", + "value": "Access-Control-Request-Headers" + }, + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Content-Length", + "value": "0" + }, + { + "key": "Cache-Control", + "value": "no-cache, no-store, max-age=0, must-revalidate" + }, + { + "key": "Pragma", + "value": "no-cache" + }, + { + "key": "Expires", + "value": "0" + }, + { + "key": "X-Content-Type-Options", + "value": "nosniff" + }, + { + "key": "X-Frame-Options", + "value": "DENY" + }, + { + "key": "X-XSS-Protection", + "value": "1 ; mode=block" + }, + { + "key": "Referrer-Policy", + "value": "no-referrer" + } + ], + "cookie": [], + "body": "" + } + ] + } + ], + "event": [ + { + "listen": "prerequest", + "script": { + "id": "ac0bd38e-a1ae-48ea-9a99-e09c59dada9a", + "type": "text/javascript", + "exec": [ + "" + ] + } + }, + { + "listen": "test", + "script": { + "id": "ce5f2837-00f5-4dde-9a45-2460c6cebd12", + "type": "text/javascript", + "exec": [ + "" + ] + } + } + ], + "variable": [ + { + "id": "3d10b67b-766c-40e4-bfc4-a2b913414336", + "key": "host", + "value": "localhost" + }, + { + "id": "ef57cc1c-95c6-4679-8da1-42d356a060fe", + "key": "port", + "value": "8081" + } + ], + "protocolProfileBehavior": {} +}
\ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 690ba134a..af25a5940 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -132,6 +132,15 @@ CDS Designer UI ui/designer +Offered APIs +---------------------------------- + +.. toctree:: + :maxdepth: 3 + + api-reference/index + + Controller Design Studio Presentation ------------------------------------- |