API documentation for services

This patch adds services documentation to api-ref.

Change-Id: If2e3beb92f16d46a54b4eb6152718c93abaf04a3
Implements: blueprint api-add-services

api-ref/source/index.rst

@@ -19,3 +19,4 @@ Clustering API
 .. include:: events.inc
 .. include:: webhooks.inc
 .. include:: actions.inc
+.. include:: services.inc

api-ref/source/parameters.yaml

@@ -452,6 +452,13 @@ attr_value:
     The attribute value on a specific node. The value could be of any data
     type that is valid for the attribute.
 
+binary:
+  type: string
+  in: body
+  required: True
+  description: |
+    The binary name of the service.
+
 build_info:
   type: object
   in: body
@@ -668,6 +675,13 @@ destroy_after_deletion:
     Whether deleted nodes to be destroyed right away.
   min_version: 1.4
 
+disabled_reason:
+  type: string
+  in: body
+  required: False
+  description: |
+    The reason for disabling a service.
+
 domain:
   type: UUID
   in: body
@@ -735,6 +749,13 @@ health_check:
     scaling.
   min_version: 1.7
 
+host:
+  type: string
+  in: body
+  required: True
+  description: |
+    The name of the host.
+
 index:
   type: integer
   in: body
@@ -1251,6 +1272,34 @@ scale_count:
     The interpretation is depending on the action requested. Default value is
     1.
 
+service_id:
+  type: UUID
+  in: body
+  required: True
+  description: |
+    A UUID that uniquely identifies an service object.
+
+service_state:
+  type: string
+  in: body
+  required: True
+  description: |
+    The state of the service. One of ``up`` or ``down``.
+
+service_status:
+  type: string
+  in: body
+  required: True
+  description: |
+    The status of the service. One of ``enabled`` or ``disabled``.
+
+services:
+  type: array
+  in: body
+  required: True
+  description: |
+    A list of service.
+
 start_time:
   type: float
   in: body
@@ -1281,6 +1330,13 @@ timeout_req:
   description: |
     The new timeout value (in seconds) of cluster operations.
 
+topic:
+  type: string
+  in: body
+  required: True
+  description: |
+    The topic name of the service.
+
 updated_at:
   type: string
   in: body

api-ref/source/samples/services-list-response.json

@@ -0,0 +1,14 @@
+{
+    "services": [
+        {
+            "binary": "senlin-engine",
+            "disabled_reason": null,
+            "host": "host1",
+            "id": "f93f83f6-762b-41b6-b757-80507834d394",
+            "state": "up",
+            "status": "enabled",
+            "topic": "senlin-engine",
+            "updated_at": "2017-04-24T07:43:12"
+        }
+    ]
+}

api-ref/source/services.inc

@@ -0,0 +1,60 @@
+===================
+Services (services)
+===================
+
+Lists all services for senlin engine.
+
+
+List services
+===================
+
+.. rest_method::  GET /v1/services
+
+   min_version: 1.7
+
+This API is only available since API microversion 1.7.
+
+Lists all services.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 503
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - OpenStack-API-Version: microversion
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - X-OpenStack-Request-ID: request_id
+  - services: services
+  - binary: binary
+  - disabled_reason: disabled_reason
+  - host: host
+  - id: service_id
+  - state: service_state
+  - status: service_status
+  - topic: topic
+  - updated_at: updated_at
+
+Response Example
+----------------
+
+.. literalinclude:: samples/services-list-response.json
+   :language: javascript