diff --git a/api-ref/source/health.inc b/api-ref/source/health.inc new file mode 100644 index 000000000..2964adfd6 --- /dev/null +++ b/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 + diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index f44d0856f..b9b685162 100644 --- a/api-ref/source/index.rst +++ b/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 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 300777e12..f9bde2803 100644 --- a/api-ref/source/parameters.yaml +++ b/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. + diff --git a/api-ref/source/samples/health-response.json b/api-ref/source/samples/health-response.json new file mode 100644 index 000000000..2d50b239f --- /dev/null +++ b/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 + } + } + } +}