summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJakobKrieg <jakob.krieg@bcmsolutions.de>2020-11-18 15:53:30 +0100
committerJakobKrieg <jakob.krieg@bcmsolutions.de>2020-11-18 15:56:37 +0100
commitb1da7d99a9976016dedf6ff53a526b51de646c9c (patch)
tree1f9c1853940a17e1cafbf153927daecefa4f2837
parent17707e6531d3986e43020725a3de06351d387226 (diff)
CDS Api reference add index, template, first APIs
Issue-ID: CCSDK-2992 Change-Id: Iad8524cce702deb7f35650b9bd69b6690c0ecc6d Signed-off-by: JakobKrieg <jakob.krieg@bcmsolutions.de>
-rw-r--r--docs/api-reference/api-doc-template.rst205
-rw-r--r--docs/api-reference/bp-processor.rst216
-rw-r--r--docs/api-reference/index.rst12
-rw-r--r--docs/api-reference/media/bp-processor.postman_collection.json220
-rw-r--r--docs/index.rst9
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
-------------------------------------