Adds API documentation for list and show hosts.

Adds v2 and v3 API documentation for list all hosts and show host details.

Change-Id: I43791fded823cd931c2d77a11fa502b2cb5f0105
Closes-Bug: #1558257

api-ref/source/v2/hosts.inc

@@ -0,0 +1,81 @@
+.. -*- rst -*-
+
+Hosts extension (os-hosts)
+====================================
+
+Administrators only, depending on policy settings.
+
+Lists, shows hosts.
+
+
+List all hosts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v2/{admin_tenant_id}/os-hosts
+
+Lists all hosts summary info that is not disabled.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - admin_tenant_id: admin_tenant_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - service-status: service_status
+   - service: host_service
+   - zone: availability_zone_3
+   - service-state: service_state
+   - host_name: hostname
+   - last-update: updated_at
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/hosts-list-response.json
+   :language: javascript
+
+Show Host Details
+~~~~~~~~~~~~~~~~~
+
+.. rest_method:: GET /v2/{admin_tenant_id}/os-hosts/{host_name}
+
+Shows details for a host.
+
+Normal response codes: 200
+
+Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - admin_tenant_id: admin_tenant_id
+  - host_name: hostname
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - volume_count: total_count
+  - total_volume_gb: totalGigabytesUsed
+  - total_snapshot_gb: totalSnapshotsUsed
+  - project: admin_tenant_id
+  - host: host
+  - snapshot_count: totalSnapshotsUsed
+
+**Example Show Host Details**
+
+.. literalinclude:: ./samples/hosts-get-response.json
+   :language: javascript

api-ref/source/v2/index.rst

@@ -12,6 +12,7 @@ Block Storage API V2 (DEPRECATED)
 .. include:: capabilities-v2.inc
 .. include:: os-cgsnapshots-v2.inc
 .. include:: consistencygroups-v2.inc
+.. include:: hosts.inc
 .. include:: limits.inc
 .. include:: os-vol-image-meta-v2.inc
 .. include:: os-vol-pool-v2.inc

api-ref/source/v2/parameters.yaml

@@ -590,6 +590,12 @@ host_name:
   in: body
   required: false
   type: string
+host_service:
+  description: |
+    The name of the service which is running on the host.
+  in: body
+  required: true
+  type: string
 id:
   description: |
     The UUID of the volume transfer.
@@ -1277,6 +1283,18 @@ security_groups:
   in: body
   required: true
   type: integer
+service_state:
+  description: |
+    The state of the service. One of ``available`` or ``unavailable``.
+  in: body
+  required: true
+  type: string
+service_status:
+  description: |
+    The status of the service. One of ``enabled`` or ``disabled``.
+  in: body
+  required: true
+  type: string
 size:
   description: |
     The size of the volume, in gibibytes (GiB).
@@ -1434,6 +1452,12 @@ total_capacity:
   in: body
   required: true
   type: string
+total_count:
+  description: |
+    Total number of volumes.
+  in: body
+  required: true
+  type: integer
 totalBackupGigabytesUsed:
   description: |
     The total number of backups gibibytes (GiB) used.

api-ref/source/v2/samples/hosts-get-response.json

@@ -0,0 +1,22 @@
+{
+    "host": [{
+            "resource": {
+                "volume_count": "8",
+                "total_volume_gb": "11",
+                "total_snapshot_gb": "1",
+                "project": "(total)",
+                "host": "node1@rbd-sas",
+                "snapshot_count": "1"
+            }
+        },
+        {
+            "resource": {
+                "volume_count": "8",
+                "total_volume_gb": "11",
+                "total_snapshot_gb": "1",
+                "project": "f21a9c86d7114bf99c711f4874d80474",
+                "host": "node1@rbd-sas",
+                "snapshot_count": "1"
+            }
+        }]
+}

api-ref/source/v2/samples/hosts-list-response.json

@@ -0,0 +1,26 @@
+{
+    "hosts": [{
+        "service-status": "available",
+        "service": "cinder-backup",
+        "zone": "nova",
+        "service-state": "enabled",
+        "host_name": "node1",
+        "last-update": "2017-03-09T21:38:41.000000"
+    },
+    {
+        "service-status": "available",
+        "service": "cinder-scheduler",
+        "zone": "nova",
+        "service-state": "enabled",
+        "host_name": "node1",
+        "last-update": "2017-03-09T21:38:38.000000"
+    },
+    {
+        "service-status": "available",
+        "service": "cinder-volume",
+        "zone": "nova",
+        "service-state": "enabled",
+        "host_name": "node1@lvm",
+        "last-update": "2017-03-09T21:38:35.000000"
+    }]
+}

api-ref/source/v3/hosts.inc

@@ -0,0 +1,81 @@
+.. -*- rst -*-
+
+Hosts extension (os-hosts)
+====================================
+
+Administrators only, depending on policy settings.
+
+Lists, shows hosts.
+
+
+List all hosts for a project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v3/{admin_project_id}/os-hosts
+
+Lists all hosts summary info that is not disabled.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - admin_project_id: admin_project_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - service-status: service_status
+   - service: host_service
+   - zone: availability_zone_3
+   - service-state: service_state
+   - host_name: hostname
+   - last-update: updated_at
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/hosts-list-response.json
+   :language: javascript
+
+Show Host Details for a project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method:: GET /v3/{admin_project_id}/os-hosts/{host_name}
+
+Shows details for a host.
+
+Normal response codes: 200
+
+Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - admin_project_id: admin_project_id
+  - host_name: hostname
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - volume_count: total_count
+  - total_volume_gb: totalGigabytesUsed
+  - total_snapshot_gb: totalSnapshotsUsed
+  - project: admin_project_id
+  - host: host
+  - snapshot_count: totalSnapshotsUsed
+
+**Example Show Host Details**
+
+.. literalinclude:: ./samples/hosts-get-response.json
+   :language: javascript

api-ref/source/v3/index.rst

@@ -15,6 +15,7 @@ Block Storage API V3 (CURRENT)
 .. include:: groups.inc
 .. include:: group-snapshots.inc
 .. include:: group-types.inc
+.. include:: hosts.inc
 .. include:: limits.inc
 .. include:: os-vol-image-meta-v3.inc
 .. include:: os-vol-pool-v3.inc

api-ref/source/v3/parameters.yaml

@@ -737,6 +737,12 @@ host_name:
   in: body
   required: false
   type: string
+host_service:
+  description: |
+    The name of the service which is running on the host.
+  in: body
+  required: true
+  type: string
 id:
   description: |
     The UUID of the volume transfer.
@@ -1461,6 +1467,18 @@ security_groups:
   in: body
   required: true
   type: integer
+service_state:
+  description: |
+    The state of the service. One of ``available`` or ``unavailable``.
+  in: body
+  required: true
+  type: string
+service_status:
+  description: |
+    The status of the service. One of ``enabled`` or ``disabled``.
+  in: body
+  required: true
+  type: string
 size:
   description: |
     The size of the volume, in gibibytes (GiB).

api-ref/source/v3/samples/hosts-get-response.json

@@ -0,0 +1,22 @@
+{
+    "host": [{
+            "resource": {
+                "volume_count": "8",
+                "total_volume_gb": "11",
+                "total_snapshot_gb": "1",
+                "project": "(total)",
+                "host": "node1@rbd-sas",
+                "snapshot_count": "1"
+            }
+        },
+        {
+            "resource": {
+                "volume_count": "8",
+                "total_volume_gb": "11",
+                "total_snapshot_gb": "1",
+                "project": "f21a9c86d7114bf99c711f4874d80474",
+                "host": "node1@rbd-sas",
+                "snapshot_count": "1"
+            }
+        }]
+}

api-ref/source/v3/samples/hosts-list-response.json

@@ -0,0 +1,26 @@
+{
+    "hosts": [{
+        "service-status": "available",
+        "service": "cinder-backup",
+        "zone": "nova",
+        "service-state": "enabled",
+        "host_name": "node1",
+        "last-update": "2017-03-09T21:38:41.000000"
+    },
+    {
+        "service-status": "available",
+        "service": "cinder-scheduler",
+        "zone": "nova",
+        "service-state": "enabled",
+        "host_name": "node1",
+        "last-update": "2017-03-09T21:38:38.000000"
+    },
+    {
+        "service-status": "available",
+        "service": "cinder-volume",
+        "zone": "nova",
+        "service-state": "enabled",
+        "host_name": "node1@lvm",
+        "last-update": "2017-03-09T21:38:35.000000"
+    }]
+}