Documentation health resource

src/main/asciidoc/health.adoc

@@ -0,0 +1,81 @@
+== Health ==
+
+Each REST API exposes a health resource which simply returns the current status of the service.
+
+When invoked without any access token, the resource simply returns its status. The status code is either ```200 OK``` when the service is up or partialy available, or `503 Service Unavailable` when the service is down or out of service.
+
+.Sample service is up
+```json
+{
+    "status": "up"
+}
+```
+
+When invoked with an access token containing a scope ```scope:health```, the resource returns details of its subsystems or components.
+
+.Sample service is down
+```json
+{
+    "status": "down",
+    "details": {
+        "dataStore": {
+            "status": "down"
+        },
+        "queues": {
+            "status": "up"
+        }
+    }
+}
+```
+
+The resource is formalized in the swagger file: https://www.gcloud.belgium.be/rest/swagger/health-swagger.yaml
+
+[cols="1,2,3"]
+|===
+|​​​​​​​​​<<get>>
+|/health
+|Check the health status of the API.
+
+3+|Response
+
+|body
+a|The status of the service. Details are shown when the client presents a valid access token with ```scope:health```.
+a|
+[source,json]
+----
+​​​{
+   "status": "up"
+}
+
+{
+  "status": "down",
+  "details": {
+    "datastore": {
+      "status": "outOfService"
+    }
+  }
+}
+----
+
+3+|Response codes
+​​|<<http-200,200>>
+|OK
+|When service is `up` or `degraded`
+​
+​​|<<http-503,503>>
+|Service Unavailable
+|When service is `down` or `outOfService`
+
+|===
+
+=== Status levels ===
+The health resource returns one of the following status levels indicating the component or system:
+
+[cols="1,1,4", options="header"]
+|===
+|Status|Status Code|Description
+|up| 200|is functioning as expected.
+|degraded| 200|is partly unavailable but service can be continued with reduced functionality.
+|down| 503|is suffering unexpected failures
+|outOfService| 503|has been taken out of service and should not be used.
+|===

src/main/asciidoc/index.adoc

@@ -66,6 +66,6 @@ include::tracing.adoc[]
 
 // include::oauth.adoc[]
 
-//include::monitoring.adoc[]
+include::health.adoc[]
 
 //include::caching.adoc[]

src/main/asciidoc/swagger/health-swagger.yaml

@@ -0,0 +1,84 @@
+swagger: "2.0"
+info:
+  title: Template for healthCheck
+  version: "1.0"
+  description: healthCheck allows to retrieve the status of the API.
+tags:
+  - name: Monitoring
+paths:
+  /health:
+    get:
+      tags:
+        - Monitoring
+      summary: Check health of the service
+      description: This resource is only available to supervision users
+      operationId: checkHealth
+      externalDocs:
+        url: https://www.gcloud.belgium.be/rest/#health
+      produces:
+        - application/json
+      security:
+        - "oauth_implicit": ["scope:health"] # details also the components which are down
+        - "oauth_implicit": [] # only returns up/down
+      responses:
+        "200":
+          description: The service is UP
+          schema:
+            $ref: "#/definitions/HealthStatus"
+          examples:
+            application/json:
+              {
+                "status": "up"
+              }
+        "503":
+          description: The service is down or outOfService
+          schema:
+            $ref: "#/definitions/HealthStatus"
+          examples: {
+            "application/json":
+              {
+                "status": "down",
+                "details": {
+                  "datastore": {
+                    "status": "outOfService"
+                  }
+                }
+              }
+          }
+securityDefinitions:
+  oauth_implicit:
+    type: oauth2
+    authorizationUrl: https://example.com/api/oauth/authorize
+    flow: implicit
+definitions:
+  HealthStatus:
+    description: Response message for the API health
+    type: object
+    required:
+      - status
+    properties:
+      status:
+        $ref: "#/definitions/HealthLevel"
+      details:
+        type: object
+        additionalProperties:
+          $ref: "#/definitions/ComponentStatus"
+  ComponentStatus:
+    description: Status of a service component
+    type: object
+    required:
+      - status
+    properties:
+      status:
+        $ref: "#/definitions/HealthLevel"
+      message:
+        description: Optional description clarifying the health status of the component
+        type: string
+  HealthLevel:
+    description: Level indicating the health status of the service
+    type: string
+    enum:
+      - up # is functioning as expected
+      - degraded # is partly unavailable but service can be continued with reduced functionality
+      - down # is suffering unexpected failures
+      - outOfService # has been taken out of service and should not be used

src/main/asciidoc/swagger/swagger.yaml

@@ -0,0 +1,13 @@
+swagger: "2.0"
+info:
+  title: Demo service
+  version: "1.0"
+  description: healthCheck allows to retrieve the status of the API.
+basePath: /demo/v1
+tags:
+  - name: Monitoring
+schemes:
+  - https
+paths:
+  /health:
+    $ref: "./health-swagger.yaml#/paths/~1health"