Add `Health` api ref

Change-Id: I796530b3481d131be23a759d23415149815d3179

api-ref/source/health.inc

@@ -0,0 +1,66 @@
+===============
+Health (health)
+===============
+
+Ping
+====
+
+.. rest_method::  GET /v2/ping
+
+Simple health check for end user.
+
+A request to ping Zaqar server when server is working returns 204, otherwise
+returns 503. This can be a handy API for end user to check if the messaging
+service is in working status.
+
+Normal response codes: 204
+
+Error response codes:
+
+- ServiceUnavailable (503)
+
+
+This operation does not accept a request body and does not return a response
+body.
+
+
+Health
+======
+
+.. rest_method::  GET /v2/health
+
+Detailed health check for cloud operator/admin.
+
+This is an ``admin only`` API. A request to get detailed health information
+of Zaqar server.
+
+The response body will depend on the storage setting of Zaqar server. By
+default, there is no pool created. Then the response body will only
+contain the ``catalog_reachable``. Otherwise, the response body will have
+``catalog_reachable`` and the health status for each pool.
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+- ServiceUnavailable (503)
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - catalog_reachable: catalog_reachable
+  - storage_reachable: storage_reachable
+  - operation_status: operation_status
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/health-response.json
+   :language: javascript
+

api-ref/source/index.rst

@@ -21,3 +21,4 @@ Messaging Service API v2 (CURRENT)
 .. include:: queues.inc
 .. include:: claims.inc
 .. include:: subscription.inc
+.. include:: health.inc

api-ref/source/parameters.yaml

@@ -190,3 +190,32 @@ subscription_source:
   in: body
   description: |
     The queue name which the subscription is registered on.
+
+catalog_reachable:
+  type: boolean
+  in: body
+  required: True
+  description: |
+    A boolean value to indicate if the management(catalog) datatabse is
+    reachable or not.
+
+storage_reachable:
+  type: boolean
+  in: body
+  required: False
+  description: |
+    A boolean value to indicate if the messages(pool) datatabse is
+    reachable or not.
+
+operation_status:
+  type: dict
+  in: body
+  required: False
+  description: |
+    A dict which will contain the status for many different actions/operations.
+    For example, post_messages, delete_messages, delete queue, etc. And each
+    status is a dict which contains three items: ``seconds``, ``ref`` and
+    ``succeeded``. Seconds means how long the operation took and succeeded will
+    indicate if the actions was successful or not. Ref may contain the
+    information if the succeeded is False, otherwise it's null.
+

api-ref/source/samples/health-response.json

@@ -0,0 +1,48 @@
+{
+    "catalog_reachable": true,
+    "redis": {
+        "storage_reachable": true,
+        "operation_status": {
+            "post_messages": {
+                "seconds": 0.027673959732055664,
+                "ref": null,
+                "succeeded": true
+            },
+            "delete_messages": {
+                "seconds": 0.0028481483459472656,
+                "ref": null,
+                "succeeded": true
+            },
+            "delete_queue": {
+                "seconds": 0.017709016799926758,
+                "ref": null,
+                "succeeded": true
+            },
+            "bulk_delete_messages": {
+                "seconds": 0.03959178924560547,
+                "ref": null,
+                "succeeded": true
+            },
+            "create_queue": {
+                "seconds": 0.021075963973999023,
+                "ref": null,
+                "succeeded": true
+            },
+            "list_messages": {
+                "seconds": 0.00003504753112792969,
+                "ref": null,
+                "succeeded": true
+            },
+            "delete_claim": {
+                "seconds": 0.0006170272827148438,
+                "ref": null,
+                "succeeded": true
+            },
+            "claim_messages": {
+                "seconds": 0.008388042449951172,
+                "ref": null,
+                "succeeded": true
+            }
+        }
+    }
+}