x/mogan
Code Issues Proposed changes

Add instance related api ref

Browse Source 
Add api-ref for list instances, list detailed instances and
show instance detail apis.

Change-Id: Ieb14915266393a0585dd884469f5158292ea9ab7
This commit is contained in:
LeiZhang 2016-10-17 23:31:53 -04:00 committed by ShaoHe Feng
parent 9639edd5cd
commit a858472d4a
5 changed files with 246 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
api-ref/source/instances.inc
View File

@ -70,6 +70,135 @@ Response
:language: javascript
List Instances
===============
.. rest_method:: GET /instances
Return a list of bare metal Instances, with some useful information about each
Instance.
By default, this query will return the name, instance uuid, instance status
and description for each Instance.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401),
forbidden(403), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- fields: fields
Response
--------
.. rest_parameters:: parameters.yaml
- name: instance_name
- description: instance_description
- uuid: instance_uuid
- status: instance_status
- links: links
**Example List of Instances: JSON response**
.. literalinclude:: ../../doc/api_samples/instances/instance-list-resp.json
:language: javascript
List Instances Detailed
=======================
.. rest_method:: GET /instances/detail
Return a list of bare metal Instances with complete details.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401),
forbidden(403), conflict(409)
Request
-------
Response
--------
.. rest_parameters:: parameters.yaml
- name: instance_name
- description: instance_description
- instance_type_uuid: typeRef
- image_uuid: imageRef
- availability_zone: availability_zone
- network_info: network_info
- links: links
- uuid: instance_uuid
- status: instance_status
- power_state: instance_power_state
- project_id: project_id_body
- user_id: user_id_body
- updated_at: updated_at
- created_at: created_at
**Example Detailed list of Instances: JSON response**
.. literalinclude:: ../../doc/api_samples/instances/instance-list-detail-resp.json
:language: javascript
Show Instance Details
=====================
.. rest_method:: GET /instances/{instance_ident}
Shows details for a instance. By default, this will return the full
representation of the resource; an optional fields parameter can be supplied to
return only the specified set.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401),
forbidden(403), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- instance_ident: instance_ident
- fields: fields
Response
--------
.. rest_parameters:: parameters.yaml
- name: instance_name
- description: instance_description
- instance_type_uuid: typeRef
- image_uuid: imageRef
- availability_zone: availability_zone
- network_info: network_info
- links: links
- uuid: instance_uuid
- status: instance_status
- power_state: instance_power_state
- project_id: project_id_body
- user_id: user_id_body
- updated_at: updated_at
- created_at: created_at
**Example Instance Details: JSON response**
.. literalinclude:: ../../doc/api_samples/instances/instance-detail-resp.json
:language: javascript
===============================
Instance Management (instances)
===============================

13
api-ref/source/parameters.yaml
View File

@ -35,6 +35,19 @@ type_uuid_path:
type: string
# variables in query
fields:
description: |
One or more fields to be returned in the response.
For example, the following request returns only the ``uuid``
and ``name`` fields for each instance:
::
GET /v1/instances?fields=uuid,name
in: query
required: false
type: array
user_id:
description: |
Filters the response by a user, by ID.

40
doc/api_samples/instances/instance-detail-resp.json Normal file
View File

@ -0,0 +1,40 @@
{
"availability_zone": null,
"created_at": "2016-10-17T04:12:41+00:00",
"description": "this is a test instance",
"image_uuid": "ac3b2291-b9ef-45f6-8eeb-21ac568a64a5",
"instance_type_uuid": "28708dff-283c-449e-9bfa-a48c93480c86",
"links": [
{
"href": "http://localhost:6688/v1/instances/f978ef48-d4af-4dad-beec-e6174309bc71",
"rel": "self"
},
{
"href": "http://localhost:6688/instances/f978ef48-d4af-4dad-beec-e6174309bc71",
"rel": "bookmark"
}
],
"name": "test_instance",
"network_info": {
"12cffc4a-b845-409e-b589-7c84be4b10d9": {
"fixed_ips": [
{
"ip_address": "172.24.4.4",
"subnet_id": "a9d47430-f90b-4513-af5f-6315af54de7d"
},
{
"ip_address": "2001:db8::a",
"subnet_id": "5e7b3e2d-f36f-4e30-874c-16c2d126fe53"
}
],
"mac_address": "52:54:00:6c:c4:17",
"network": "ade2b658-929b-439f-9528-c47057960942"
}
},
"power_state": "power on",
"project_id": "c18e8a1a870d4c08a0b51ced6e0b6459",
"status": "building",
"updated_at": "2016-10-17T04:12:44+00:00",
"user_id": "cdbf77d47f1d4d04ad9b7ff62b672467",
"uuid": "f978ef48-d4af-4dad-beec-e6174309bc71"
}

44
doc/api_samples/instances/instance-list-detail-resp.json Normal file
View File

@ -0,0 +1,44 @@
{
"instances": [
{
"availability_zone": null,
"created_at": "2016-10-17T04:12:41+00:00",
"description": "this is a test instance",
"image_uuid": "ac3b2291-b9ef-45f6-8eeb-21ac568a64a5",
"instance_type_uuid": "28708dff-283c-449e-9bfa-a48c93480c86",
"links": [
{
"href": "http://localhost:6688/v1/instances/f978ef48-d4af-4dad-beec-e6174309bc71",
"rel": "self"
},
{
"href": "http://localhost:6688/instances/f978ef48-d4af-4dad-beec-e6174309bc71",
"rel": "bookmark"
}
],
"name": "test_instance",
"network_info": {
"12cffc4a-b845-409e-b589-7c84be4b10d9": {
"fixed_ips": [
{
"ip_address": "172.24.4.4",
"subnet_id": "a9d47430-f90b-4513-af5f-6315af54de7d"
},
{
"ip_address": "2001:db8::a",
"subnet_id": "5e7b3e2d-f36f-4e30-874c-16c2d126fe53"
}
],
"mac_address": "52:54:00:6c:c4:17",
"network": "ade2b658-929b-439f-9528-c47057960942"
}
},
"power_state": "power on",
"project_id": "c18e8a1a870d4c08a0b51ced6e0b6459",
"status": "building",
"updated_at": "2016-10-17T04:12:44+00:00",
"user_id": "cdbf77d47f1d4d04ad9b7ff62b672467",
"uuid": "f978ef48-d4af-4dad-beec-e6174309bc71"
}
]
}

20
doc/api_samples/instances/instance-list-resp.json Normal file
View File

@ -0,0 +1,20 @@
{
"instances": [
{
"description": "this is a test instance",
"links": [
{
"href": "http://localhost:6688/v1/instances/f978ef48-d4af-4dad-beec-e6174309bc71",
"rel": "self"
},
{
"href": "http://localhost:6688/instances/f978ef48-d4af-4dad-beec-e6174309bc71",
"rel": "bookmark"
}
],
"name": "test_instance",
"status": "building",
"uuid": "f978ef48-d4af-4dad-beec-e6174309bc71"
}
]
}