Create mservices api reference

Add details for mservices API of Magnum.

Implements: blueprint magnum-doc-rest-api

Change-Id: I2beba238e12fd6f23a10a1a6b14d1fce0f5066cf

api-ref/source/mservices.inc

@@ -0,0 +1,49 @@
+.. -*- rst -*-
+
+=====================
+Manage Magnum service
+=====================
+
+Show container infrastructure management service status
+=======================================================
+
+.. rest_method::  GET /v1/mservices
+
+Enables administrative users to view details for all Magnum services.
+
+Container infrastructure service status details include service id, binary,
+host, report count, creation time, last updated time, health status, and
+the reason for disabling service.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - mservices: mservices
+   - binary: binary
+   - created_at: created_at
+   - state: state
+   - report_count: report_count
+   - updated_at: updated_at
+   - host: host
+   - disabled_reason: disabled_reason
+   - id: id_s
+
+Response Example
+----------------
+
+.. literalinclude:: samples/mservice-get-resp.json
+   :language: javascript

api-ref/source/parameters.yaml

@@ -1,9 +1,59 @@
+request_id:
+  type: UUID
+  in: header
+  required: true
+  description: |
+    A unique ID for tracking service request. The request ID associated
+    with the request by default appears in the service logs.
+binary:
+  type: string
+  in: body
+  required: true
+  description: |
+    The name of the binary form of the Magnum service.
+created_at:
+  description: |
+    The date and time when the resource was created.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+  in: body
+  required: true
+  type: string
 description:
   description: |
     Descriptive text about the Magnum service.
   in: body
   required: true
   type: string
+disabled_reason:
+  description: |
+    The disable reason of the service, ``null`` if the service is enabled or
+    disabled without reason provided.
+  in: body
+  required: true
+  type: string
+host:
+  description: |
+    The host for the service.
+  in: body
+  required: true
+  type: string
+id_s:
+  description: |
+    The ID of the Magnum service.
+  in: body
+  required: true
+  type: string
 links:
   description: |
     Links to the resources in question. See `API Guide / Links and
@@ -13,19 +63,51 @@ links:
   in: body
   required: true
   type: array
+mservices:
+  description: |
+    A list of Magnum services.
+  in: body
+  required: true
+  type: array
 name:
   description: |
     Name of the Container Infrastructure Management API.
   in: body
   required: true
   type: string
-request_id:
-  type: UUID
-  in: header
-  required: true
+report_count:
   description: |
-    A unique ID for tracking service request. The request ID associated
-    with the request by default appears in the service logs.
+    The total number of report.
+  in: body
+  required: true
+  type: integer
+state:
+  description: |
+    The current state of Magnum services.
+  in: body
+  required: true
+  type: string
+updated_at:
+  description: |
+    The date and time when the resource was updated.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC. In the previous example, the offset value is ``-05:00``.
+
+    If the ``updated_at`` date and time stamp is not set, its value is
+    ``null``.
+  in: body
+  required: true
+  type: string
 version:
   description: |
     The version.
@@ -64,4 +146,5 @@ version_status:
 
     - ``CURRENT``: this is the preferred version of the API to use
     - ``SUPPORTED``: this is an older, but still supported version of the API
-    - ``DEPRECATED``: a deprecated version of the API that is slated for removal
+    - ``DEPRECATED``: a deprecated version of the API that is slated for removal
+

api-ref/source/samples/mservice-get-resp.json

@@ -0,0 +1,14 @@
+{
+   "mservices":[
+      {
+         "binary":"magnum-conductor",
+         "created_at":"2016-08-23T10:52:13+00:00",
+         "state":"up",
+         "report_count":2179,
+         "updated_at":"2016-08-25T01:13:16+00:00",
+         "host":"magnum-manager",
+         "disabled_reason":null,
+         "id":1
+      }
+   ]
+}