From 3431a15a1023ad78450c251d38ffded7d8d500a8 Mon Sep 17 00:00:00 2001 From: Xinran Wang Date: Mon, 30 Mar 2020 15:08:13 +0000 Subject: [PATCH] Finish v2 API doc Add device, deployable implemented V2 api documentation. Remove deployable-create-resp.json, deployable-patch-curl.json deployable-post-curl.json, because these APIs are removed in V2. Remove deployable-update-resp.json because this API is still work in progress, we will update this part of documentation after the API implementation done. Change-Id: I45549fc5276c091ca585652b11836b967cb239e3 --- api-ref/source/v2/deployables.inc | 48 ++++++++++++ api-ref/source/v2/devices.inc | 47 ++++++++++++ api-ref/source/v2/index.rst | 4 + api-ref/source/v2/parameters.yaml | 14 ++++ .../deployables/deployable-create-resp.json | 36 --------- .../deployables/deployable-patch-curl.json | 10 --- .../deployables/deployable-post-curl.json | 26 ------- .../deployables/deployable-update-resp.json | 72 ------------------ .../deployables/deployables-getone-resp.json | 54 ++++++-------- .../deployables/deployables-list-resp.json | 74 ++++++------------- .../devices/devices-getone-resp.json | 18 +++++ .../devices/devices-list-resp.json | 23 ++++++ 12 files changed, 197 insertions(+), 229 deletions(-) create mode 100644 api-ref/source/v2/deployables.inc create mode 100644 api-ref/source/v2/devices.inc delete mode 100644 doc/api_samples/deployables/deployable-create-resp.json delete mode 100644 doc/api_samples/deployables/deployable-patch-curl.json delete mode 100644 doc/api_samples/deployables/deployable-post-curl.json delete mode 100644 doc/api_samples/deployables/deployable-update-resp.json create mode 100644 doc/api_samples/devices/devices-getone-resp.json create mode 100644 doc/api_samples/devices/devices-list-resp.json diff --git a/api-ref/source/v2/deployables.inc b/api-ref/source/v2/deployables.inc new file mode 100644 index 00000000..61431fbe --- /dev/null +++ b/api-ref/source/v2/deployables.inc @@ -0,0 +1,48 @@ +.. -*- rst -*- +.. needs:body_verification + +Deployables ++++++++++++ + +Lists, shows details for deployables. + +A `deployables` represent a logical unit of an acceleration card, such as re-configurable +region of an FPGA card. + +List Deployables +---------------- + +.. rest_method:: GET /v2/deployables + +Lists UUIDs, names, attribute list and more informations for all deployables. + +Normal response codes: 200 + +Error response codes: unauthorized(401), forbidden(403) + +**Example response: list all deployables** + +.. literalinclude:: ../../../doc/api_samples/deployables/deployables-list-resp.json + :language: javascript + +Get One Deployable +------------------ + +.. rest_method:: GET /v2/deployables/{deployable_uuid} + +Gets the UUID, name, attribute list and more informations for one deployable with the specified UUID. + +Normal response codes: 200 + +Error response codes: badRequest(400), unauthorized(401), forbidden(403) + +Request +======= +.. rest_parameters:: parameters.yaml + + - deployable_uuid: deployable_uuid + +**Example response: show details of a specific deployable** + +.. literalinclude:: ../../../doc/api_samples/deployables/deployables-getone-resp.json + :language: javascript diff --git a/api-ref/source/v2/devices.inc b/api-ref/source/v2/devices.inc new file mode 100644 index 00000000..c217d21f --- /dev/null +++ b/api-ref/source/v2/devices.inc @@ -0,0 +1,47 @@ +.. -*- rst -*- +.. needs:body_verification + +Devices ++++++++ + +Lists, shows details for devices. + +A `device` represent a physical card like FPGA card or GPU card. + +List Devices +------------ + +.. rest_method:: GET /v2/devices + +Lists UUIDs, names, type and more informations for all devices. + +Normal response codes: 200 + +Error response codes: unauthorized(401), forbidden(403) + +**Example response: list all devices** + +.. literalinclude:: ../../../doc/api_samples/devices/devices-list-resp.json + :language: javascript + +Get One Device +-------------- + +.. rest_method:: GET /v2/devices/{device_uuid} + +Gets the UUID, name, type and more informations for one device with the specified UUID. + +Normal response codes: 200 + +Error response codes: badRequest(400), unauthorized(401), forbidden(403) + +Request +======= +.. rest_parameters:: parameters.yaml + + - device_uuid: device_uuid + +**Example response: show details of a specific device** + +.. literalinclude:: ../../../doc/api_samples/devices/devices-getone-resp.json + :language: javascript diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index 72d9a441..bf1c6f86 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -12,3 +12,7 @@ in Ussuri. .. include:: device_profile.inc .. include:: arqs.inc + +.. include:: devices.inc + +.. include:: deployables.inc diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index e4b7b1bb..84a340d7 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -5,6 +5,13 @@ accelerator_request_uuid: in: path required: true type: string +deployable_uuid: + description: | + The UUID of the deployable. + This must be a valid UUID otherwise API will return 400. + in: path + required: true + type: string device_profile_name: description: | The display name of a device profile. @@ -18,6 +25,13 @@ device_profile_uuid: in: path required: true type: string +device_uuid: + description: | + The UUID of the device. + This must be a valid UUID otherwise API will return 400. + in: path + required: true + type: string # variables in body device_prof_groups_req: description: | diff --git a/doc/api_samples/deployables/deployable-create-resp.json b/doc/api_samples/deployables/deployable-create-resp.json deleted file mode 100644 index a77d5fa7..00000000 --- a/doc/api_samples/deployables/deployable-create-resp.json +++ /dev/null @@ -1,36 +0,0 @@ -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" -} diff --git a/doc/api_samples/deployables/deployable-patch-curl.json b/doc/api_samples/deployables/deployable-patch-curl.json deleted file mode 100644 index 0a4b1192..00000000 --- a/doc/api_samples/deployables/deployable-patch-curl.json +++ /dev/null @@ -1,10 +0,0 @@ -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"}]' diff --git a/doc/api_samples/deployables/deployable-post-curl.json b/doc/api_samples/deployables/deployable-post-curl.json deleted file mode 100644 index adb0b47f..00000000 --- a/doc/api_samples/deployables/deployable-post-curl.json +++ /dev/null @@ -1,26 +0,0 @@ -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 -}' diff --git a/doc/api_samples/deployables/deployable-update-resp.json b/doc/api_samples/deployables/deployable-update-resp.json deleted file mode 100644 index b07138cf..00000000 --- a/doc/api_samples/deployables/deployable-update-resp.json +++ /dev/null @@ -1,72 +0,0 @@ -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 -} diff --git a/doc/api_samples/deployables/deployables-getone-resp.json b/doc/api_samples/deployables/deployables-getone-resp.json index 3f77b607..d9ffe68e 100644 --- a/doc/api_samples/deployables/deployables-getone-resp.json +++ b/doc/api_samples/deployables/deployables-getone-resp.json @@ -1,35 +1,25 @@ -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" +{ + "uuid": "29e23349-12ee-4978-963c-11484a4ae601", + "parent_id": null, + "root_id": null, + "name": "computenode_FakeDevice", + "num_accelerators": 16, + "device_id": 1, + "attributes_list": "[{'traits1': 'CUSTOM_FAKE_DEVICE'}, {'rc': 'FPGA'}]", + "rp_uuid": "853f07a6-19de-3dd6-b9f6-6c782daa3f7b", + "driver_name": "fake", + "bitstream_id": null, + "created_at": "2020-03-13T02:27:35+00:00", + "updated_at": "2020-03-13T02:27:36+00:00", + "links": + [ + { + "href": "http://localhost/accelerator/v2/deployables/29e23349-12ee-4978-963c-11484a4ae601", + "rel": "self" }, - { - "href":"http://192.168.23.76:6666/deployables/6a477822-4598-4a1a-ae6f-c4f9d370e4aa", - "rel":"bookmark" + { + "href": "http://localhost/accelerator/deployables/29e23349-12ee-4978-963c-11484a4ae601", + "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" + ] } diff --git a/doc/api_samples/deployables/deployables-list-resp.json b/doc/api_samples/deployables/deployables-list-resp.json index e742696f..980abe48 100644 --- a/doc/api_samples/deployables/deployables-list-resp.json +++ b/doc/api_samples/deployables/deployables-list-resp.json @@ -1,62 +1,30 @@ { - "deployables":[ + "deployables": + [ { - "instance_uuid":null, - "assignable":false, - "vendor":"ZTE", - "parent_uuid":null, - "links":[ + "uuid": "29e23349-12ee-4978-963c-11484a4ae601", + "parent_id": null, + "root_id": null, + "name": "computenode_FakeDevice", + "num_accelerators": 16, + "device_id": 1, + "attributes_list": "[{'traits1': 'CUSTOM_FAKE_DEVICE'}, {'rc': 'FPGA'}]", + "rp_uuid": "853f07a6-19de-3dd6-b9f6-6c782daa3f7b", + "driver_name": "fake", + "bitstream_id": null, + "created_at": "2020-03-13T02:27:35+00:00", + "updated_at": "2020-03-13T02:27:36+00:00", + "links": + [ { - "href":"http://192.168.23.76/v1/deployables/9044a4ae-a9d7-4554-97e4-fc63626a4b08", - "rel":"self" + "href": "http://localhost/accelerator/v2/deployables/29e23349-12ee-4978-963c-11484a4ae601", + "rel": "self" }, { - "href":"http://192.168.23.76/deployables/9044a4ae-a9d7-4554-97e4-fc63626a4b08", - "rel":"bookmark" + "href": "http://localhost/accelerator/deployables/29e23349-12ee-4978-963c-11484a4ae601", + "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 + ] } ] } diff --git a/doc/api_samples/devices/devices-getone-resp.json b/doc/api_samples/devices/devices-getone-resp.json new file mode 100644 index 00000000..3484104b --- /dev/null +++ b/doc/api_samples/devices/devices-getone-resp.json @@ -0,0 +1,18 @@ +{ + "uuid": "359c0990-0258-44fd-8b05-fc510ac3d022", + "type": "FPGA", + "vendor": "0xABCD", + "model": "miss model info", + "std_board_info": "{'device_id': '0xabcd', 'class': 'Fake class'}", + "vendor_board_info": "fake_vendor_info", + "hostname": "computenode", + "created_at": "2020-03-13T02:26:31+00:00", + "updated_at": null, + "links": + [ + { + "href": "http://localhost/accelerator/v2/devices/359c0990-0258-44fd-8b05-fc510ac3d022", + "rel": "self" + } + ] +} diff --git a/doc/api_samples/devices/devices-list-resp.json b/doc/api_samples/devices/devices-list-resp.json new file mode 100644 index 00000000..7001e796 --- /dev/null +++ b/doc/api_samples/devices/devices-list-resp.json @@ -0,0 +1,23 @@ +{ + "devices": + [ + { + "uuid": "359c0990-0258-44fd-8b05-fc510ac3d022", + "type": "FPGA", + "vendor": "0xABCD", + "model": "miss model info", + "std_board_info": "{'device_id': '0xabcd', 'class': 'Fake class'}", + "vendor_board_info": "fake_vendor_info", + "hostname": "computenode", + "created_at": "2020-03-13T02:26:31+00:00", + "updated_at": null, + "links": + [ + { + "href": "http://localhost/accelerator/v2/devices/359c0990-0258-44fd-8b05-fc510ac3d022", + "rel": "self" + } + ] + } + ] +}