This is a draft proposal for OpenAPI, or an extension thereof, which details an approach for microservices to communicate health in a detailed manour.
The depth parameter is intended so that the complete architecture underpinning a service can be discovered.
The bearer header allows services to control access to detailed health information. This also means that integration across boundaries can be controlled using different authoritive identity providers.
| swagger: "2.0" | |
| paths: | |
| /health: | |
| x-swagger-router-controller: health | |
| head: | |
| summary: Healthcheck summary | |
| operationId: healthcheckSummary | |
| description: > | |
| The status of this service based on its dependencies. | |
| No details will be given, and health is based on cached usage history of dependencies. | |
| responses: | |
| 200: | |
| description: "successful operation" | |
| 203: | |
| description: Non-critical dependency/dependencies unhealthy | |
| 500: | |
| description: This service is unhealthy, but not because of a service dependency | |
| 502: | |
| description: Critical dependency/dependencies unhealthy | |
| 503: | |
| description: This service is unavailable | |
| 504: | |
| description: Critical dependency/dependencies timing out | |
| get: | |
| summary: Healthcheck details | |
| description: > | |
| Get details of the service health, as well as details of dependent service health. | |
| This endpoint will not use cached health data unless queried with a depth of -1. | |
| operationId: healthcheckDetails | |
| produces: | |
| - "application/json" | |
| parameters: | |
| - name: depth | |
| in: query | |
| description: > | |
| The number of layers of service to be detailed. | |
| A value of `-1` will use cached data (where available) to produce a `depth=0` response. | |
| A value of `0` will utilise the `HEAD` endpoint of dependencies to fetch a summary of dependencies. | |
| A positive value will utilise the `GET` endpoint of dependencies to fetch a detailed status of dependencies. | |
| When querying dependencies, the `depth` parameter will be passed on with the value decremented by one. | |
| required: false | |
| type: integer | |
| default: 0 | |
| responses: | |
| 200: | |
| description: "successful operation" | |
| schema: | |
| $ref: "#/definitions/healthcheck-details" | |
| 203: | |
| description: Non-critical dependency/dependencies unhealthy | |
| 400: | |
| description: Validation error | |
| 401: | |
| description: Access Denied (missing/incorrect bearer token?) | |
| 403: | |
| description: Forbidden (incorrect scope?) | |
| 500: | |
| description: This service is unhealthy, but not because of a service dependency | |
| 502: | |
| description: Critical dependency/dependencies unhealthy | |
| schema: | |
| $ref: "#/definitions/healthcheck-details" | |
| 503: | |
| description: This service is unavailable | |
| 504: | |
| description: Critical dependency/dependencies timing out | |
| schema: | |
| $ref: "#/definitions/healthcheck-details" | |
| security: | |
| - bearer: | |
| - "healthcheck:read" | |
| definitions: | |
| healthcheck-details: | |
| type: object | |
| additionalProperties: true | |
| properties: | |
| name: | |
| type: string | |
| version: | |
| type: string | |
| dependencies: | |
| description: > | |
| When this property is absent, dependencies were not queried. | |
| An empty array indicates no dependencies. | |
| type: array | |
| items: | |
| $ref: "#/definitions/healthcheck-dependency" | |
| minItems: 0 | |
| required: [ name, version ] | |
| healthcheck-dependency: | |
| type: object | |
| additionalProperties: false | |
| properties: | |
| client: | |
| type: object | |
| additionalProperties: false | |
| properties: | |
| uri: | |
| type: string | |
| format: uri | |
| statusCode: | |
| type: integer | |
| service: | |
| $ref: "#/definitions/healthcheck-details" | |
| required: [ client ] |