Add deployables to api-ref

This patch adds the deployables api to api-ref

Change-Id: I8d5612c0e553e132efad3ed6ad75a4093719db88

api-ref/source/v1/deployables.inc

@@ -0,0 +1,119 @@
+.. -*- rst -*-
+.. needs:body_verification
+
+Deployables
++++++++++++
+
+Lists, creates, shows details for, updates and deletes deployables.
+
+A deployable is a component of a device that contains accelerators.
+(An accelerator is a hardware resource that offload computation; it
+is the smallest unit within a device that can be assigned to a VM.)
+
+.. note::
+
+   In the following example url requests $cyborg_endpoint_url can be
+   different depending on how cyborg-api service is running. If cyborg-api
+   service is running as a python process, use "http://localhost:6666/v1",
+   otherwise if cyborg-api is running as a WSGI application:
+   "https://docs.openstack.org/cyborg/latest/admin/config-wsgi.html",
+   use "http://localhost/accelerator/v1".
+
+List Deployables
+----------------
+
+.. rest_method:: GET /deployables
+
+Lists UUIDs, names, number of accelerators, device_ids and root_ids,
+parent_ids for all deployables.
+
+Supported query parameters:
+
+  - limit: Optional, to determinate maximum number of accelerators to return.
+  - marker: Optional, to display a list of accelerators after this marker.
+  - sort_key: Optional, to sort the returned deployables list by this
+              specified key value.
+  - sort_dir: Optional, to return the deployables list with sort direction.
+
+**Example response: list deployables**
+
+.. literalinclude:: ../../../doc/api_samples/deployables/deployables-list-resp.json
+   :language: javascript
+
+Get One Deployable
+------------------
+
+.. rest_method:: GET /deployables/uuid
+
+Gets the UUID, name, number of accelerators and other fields
+for one deployable with the specified UUID.
+
+Gets a deployable. The payload should have these fields:
+
+  - uuid: UUID
+
+**Example response: get details of a specific deployable**
+
+.. literalinclude:: ../../../doc/api_samples/deployables/deployables-getone-resp.json
+
+Create Deployable
+-----------------
+
+.. rest_method:: POST /deployables
+
+Creates a deployable. The payload should have these fields:
+
+  - uuid: UUID
+  - name: string
+  - num_accelerators: integer
+  - address: string
+  - interface_type: string
+  - assignable: boolean
+  - availability: string
+  - accelerator_id: integer
+
+**Example post curl**
+
+.. literalinclude:: ../../../doc/api_samples/deployables/deployable-post-curl.json
+
+**Example response: create a deployable**
+
+.. literalinclude:: ../../../doc/api_samples/deployables/deployable-create-resp.json
+
+Update Deployable
+-----------------
+
+.. rest_method:: PATCH /deployables/uuid
+
+Update a deployable. The payload should be a RFC 6902-compliant
+JSON patch, FYR:"http://jsonpatch.com/".
+The patch should have these fields:
+
+  - uuid: UUID
+
+Other fields are optional.
+
+**Example patch curl**
+
+.. literalinclude:: ../../../doc/api_samples/deployables/deployable-patch-curl.json
+
+**Example response: update a deployable**
+
+.. literalinclude:: ../../../doc/api_samples/deployables/deployable-update-resp.json
+
+Delete Deployable
+-----------------
+
+.. rest_method:: DELETE /deployables/uuid
+
+Delete a deployable. No query parameters required.
+
+Response will be like the following:
+
+    .. code-block:: bash
+
+        HTTP/1.1 204 No Content
+        Date: Sat, 30 Mar 2019 09:51:49 GMT
+        Server: Apache/2.4.29 (Ubuntu)
+        x-openstack-request-id: req-46603a01-f04d-40b6-922f-2f2ec1201725
+        Connection: close

api-ref/source/v1/index.rst

@@ -3,7 +3,7 @@ OpenStack Acceleration v1 APIs
 ==============================
 
 v1 APIs
-#######
+=======
 
 This is a reference for the OpenStack Acceleration v1 API which is provided by
 the Cyborg project.
@@ -13,7 +13,7 @@ the Cyborg project.
 .. include:: deployables.inc
 
 Deprecated v1 APIs
-##################
+==================
 
 This section contains references for v1 APIs which are deprecated and usually
 limited to some maximum microversion.

doc/api_samples/deployables/deployable-create-resp.json

@@ -0,0 +1,36 @@
+HTTP/1.1 201 Created
+Location: http://192.168.23.76:6666/v1/deployables/6a477822-4598-4a1a-ae6f-c4f9d370e4aa
+Content-Length: 670
+Content-Type: application/json
+X-Openstack-Request-Id: req-055ffe9c-3916-4b27-8a09-d24a8370ec4c
+Date: Wed, 27 Mar 2019 01:38:14 GMT
+
+{ 
+   "instance_uuid":null,
+   "assignable":false,
+   "vendor":"ZTE",
+   "parent_uuid":null,
+   "links":[
+      {
+         "href":"http://192.168.23.76:6666/v1/deployables/6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
+         "rel":"self"
+      },
+      {
+         "href":"http://192.168.23.76:6666/deployables/6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
+         "rel":"bookmark"
+      }
+   ],
+   "updated_at":null,
+   "interface_type":"pci",
+   "uuid":"6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
+   "name":"zte-hpts-6",
+   "created_at":"2019-03-27T01:38:14+00:00",
+   "host":"localhost",
+   "version":"1",
+   "board":"acc_board_type",
+   "address":"06.00.1",
+   "attributes_list":"[]",
+   "type":"pf",
+   "availability":"released",
+   "root_uuid":"6a477822-4598-4a1a-ae6f-c4f9d370e4aa"
+}

doc/api_samples/deployables/deployable-patch-curl.json

@@ -0,0 +1,10 @@
+curl -g -i -X PATCH $cyborg_endpoint_url/deployables/uuid \
+  -H "Accept: applicatiapplication/json" \
+  -H "OpenStack-API-Version: container-infra latest" \
+  -H "User-Agent: None" \
+  -H "X-Auth-Token: your_token" \
+  -d '
+[{"op": "replace", "path": "/assignable", "value": "false"},
+ {"op": "remove", "path": "/root_uuid"}, 
+ {"op": "add", "path": "/parent_uuid", 
+      "value": "155b5100-eaf3-4441-8694-ae17c82eddcb"}]'

doc/api_samples/deployables/deployable-post-curl.json

@@ -0,0 +1,26 @@
+curl -g -i -X POST $cyborg_endpoint_url/deployables \
+  -H "Accept: application/json" -H "Content-Type: application/json" \
+  -H "OpenStack-API-Version: container-infra latest" \
+  -H "User-Agent:None" \
+  -H "X-Auth-Token: yourtoken" \
+  -d '
+{  
+   "instance_uuid":null,
+   "assignable":false,
+   "vendor":"ZTE",
+   "parent_uuid":null,
+   "updated_at":null,
+   "interface_type":"pci",
+   "uuid":"6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
+   "name":"zte-hpts-6",
+   "created_at":null,
+   "host":"localhost",
+   "version":"1",
+   "board":"acc_board_type",
+   "address":"06.00.1",
+   "attributes_list":"[]",
+   "type":"pf",
+   "availability":"released",
+   "root_uuid":null,
+   "accelerator_id":2
+}'

doc/api_samples/deployables/deployable-update-resp.json

@@ -0,0 +1,72 @@
+Before patch:
+
+{
+   "instance_uuid":null,
+   "assignable":true,
+   "vendor":"ZTE",
+   "parent_uuid":null,
+   "links":[
+      {
+         "href":"http://192.168.23.76/v1/deployables/f1ca30c2-f28b-4b6c-b1f6-f46e4adaa63a",
+         "rel":"self"
+      },
+      {
+         "href":"http://192.168.23.76/deployables/f1ca30c2-f28b-4b6c-b1f6-f46e4adaa63a",
+         "rel":"bookmark"
+      }
+   ],
+   "updated_at":"2019-03-30T09:40:21+00:00",
+   "interface_type":"pci",
+   "uuid":"f1ca30c2-f28b-4b6c-b1f6-f46e4adaa63a",
+   "name":"zte-hpts-6",
+   "created_at":"2019-03-30T08:39:47+00:00",
+   "host":"localhost",
+   "version":"1",
+   "board":"acc_board_type",
+   "address":"06.00.1",
+   "attributes_list":"[]",
+   "type":"pf",
+   "availability":"released",
+   "root_uuid":"f1ca30c2-f28b-4b6c-b1f6-f46e4adaa63a"
+}
+
+After patch:
+
+HTTP/1.1 200 OK
+Date: Sat, 30 Mar 2019 09:40:21 GMT
+Server: Apache/2.4.29 (Ubuntu)
+Content-Length: 683
+Content-Type: application/json
+x-openstack-request-id: req-f58854f5-bf29-4380-84c1-21b70e732d0c
+Connection: close
+
+{
+   "instance_uuid":null,
+   "assignable":false,
+   "vendor":"ZTE",
+   "parent_uuid":"155b5100-eaf3-4441-8694-ae17c82eddcb",
+   "links":[
+      {
+         "href":"http://192.168.23.76/v1/deployables/f1ca30c2-f28b-4b6c-b1f6
+             -f46e4adaa63a",
+         "rel":"self"
+      },
+      {
+         "href":"http://192.168.23.76/deployables/f1ca30c2-f28b-4b6c-b1f6-f46e4adaa63a",
+         "rel":"bookmark"
+      }
+   ],
+   "updated_at":"2019-03-30T09:40:21+00:00",
+   "interface_type":"pci",
+   "uuid":"f1ca30c2-f28b-4b6c-b1f6-f46e4adaa63a",
+   "name":"zte-hpts-6",
+   "created_at":"2019-03-30T08:39:47+00:00",
+   "host":"localhost",
+   "version":"1",
+   "board":"acc_board_type",
+   "address":"06.00.1",
+   "attributes_list":"[]",
+   "type":"pf",
+   "availability":"released",
+   "root_uuid":null
+}

doc/api_samples/deployables/deployables-getone-resp.json

@@ -0,0 +1,35 @@
+HTTP/1.1 200 OK
+Content-Length: 670
+Content-Type: application/json
+X-Openstack-Request-Id: req-d1afc394-03d0-4768-8270-760e0ed5c5e9
+Date: Wed, 27 Mar 2019 02:09:29 GMT
+
+{  
+   "instance_uuid":null,
+   "assignable":false,
+   "vendor":"ZTE",
+   "parent_uuid":null,
+   "links":[  
+      {  
+         "href":"http://192.168.23.76:6666/v1/deployables/6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
+         "rel":"self"
+      },
+      {  
+         "href":"http://192.168.23.76:6666/deployables/6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
+         "rel":"bookmark"
+      }
+   ],
+   "updated_at":null,
+   "interface_type":"pci",
+   "uuid":"6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
+   "name":"zte-hpts-6",
+   "created_at":"2019-03-27T01:38:14+00:00",
+   "host":"localhost",
+   "version":"1",
+   "board":"acc_board_type",
+   "address":"06.00.1",
+   "attributes_list":"[]",
+   "type":"pf",
+   "availability":"released",
+   "root_uuid":"6a477822-4598-4a1a-ae6f-c4f9d370e4aa"
+}

doc/api_samples/deployables/deployables-list-resp.json

@@ -0,0 +1,62 @@
+{
+   "deployables":[
+      {
+         "instance_uuid":null,
+         "assignable":false,
+         "vendor":"ZTE",
+         "parent_uuid":null,
+         "links":[
+            {
+               "href":"http://192.168.23.76/v1/deployables/9044a4ae-a9d7-4554-97e4-fc63626a4b08",
+               "rel":"self"
+            },
+            {
+               "href":"http://192.168.23.76/deployables/9044a4ae-a9d7-4554-97e4-fc63626a4b08",
+               "rel":"bookmark"
+            }
+         ],
+         "updated_at":null,
+         "interface_type":"pci",
+         "uuid":"9044a4ae-a9d7-4554-97e4-fc63626a4b08",
+         "name":"zte-hpts-1",
+         "created_at":null,
+         "host":"localhost",
+         "version":"1",
+         "board":"acc_board_type",
+         "address":"06.00.1",
+         "attributes_list":"[]",
+         "type":"pf",
+         "availability":"released",
+         "root_uuid":null
+      },
+      {
+         "instance_uuid":null,
+         "assignable":false,
+         "vendor":"ZTE",
+         "parent_uuid":null,
+         "links":[
+            {
+               "href":"http://192.168.23.76/v1/deployables/155b5100-eaf3-4441-8694-ae17c82eddcb",
+               "rel":"self"
+            },
+            {
+               "href":"http://192.168.23.76/deployables/155b5100-eaf3-4441-8694-ae17c82eddcb",
+               "rel":"bookmark"
+            }
+         ],
+         "updated_at":null,
+         "interface_type":"pci",
+         "uuid":"155b5100-eaf3-4441-8694-ae17c82eddcb",
+         "name":"zte-hpts-2",
+         "created_at":null,
+         "host":"localhost",
+         "version":"1",
+         "board":"acc_board_type",
+         "address":"06.00.1",
+         "attributes_list":"[]",
+         "type":"pf",
+         "availability":"released",
+         "root_uuid":null
+      }
+   ]
+}