ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-52] API Health Check ​

Guidance ​

  • API servers SHOULD provide a health check endpoint as suggested by RFC DRAFT.
  • The API health check endpoint SHOULD be defined as /health.
  • The response of the health check API SHOULD be in application/health+json format.
  • The health check endpoint SHOULD NOT require authentication.
  • The health check response SHOULD include, at minimum:
    • status: Overall health status (PASS, FAIL, WARN)
    • version: API version
    • releaseId: Release or build identifier
  • Additional checks MAY be included based on the specific needs of the API:
    • Database connectivity
    • External service dependencies
    • Cache availability
    • Storage system health
  • The health check endpoint SHOULD respond quickly, typically within 100-500ms.
  • Sensitive information MUST NOT be exposed through the health check endpoint.

Example ​

A basic health check response:

json
{
  "status": "PASS",
  "version": "1.0.0",
  "releaseId": "1.0.0-build.1",
  "notes": ["Database connections stable", "Cache responding normally"],
  "output": "All systems operational",
  "checks": {
    "database:responseTime": [
      {
        "componentType": "datastore",
        "status": "PASS",
        "time": "2023-05-22T15:46:09Z",
        "observedValue": 23,
        "observedUnit": "ms"
      }
    ],
    "externalApi:status": [
      {
        "componentType": "system",
        "status": "PASS",
        "time": "2023-05-22T15:46:09Z"
      }
    ]
  }
}

OpenAPI 3.1 Example ​

Here's an OpenAPI 3.1 specification example for the health check endpoint:

yaml
openapi: 3.1.0
info:
  title: API Health Check
  version: 1.0.0
paths:
  /health:
    get:
      summary: Get API health status
      responses:
        '200':
          description: Successful health check response
          content:
            application/health+json:
              schema:
                type: object
                required:
                  - status
                  - version
                  - releaseId
                properties:
                  status:
                    type: string
                    enum: [PASS, FAIL, WARN]
                  version:
                    type: string
                  releaseId:
                    type: string
                  notes:
                    type: array
                    items:
                      type: string
                  output:
                    type: string
                  checks:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: object
                        required:
                          - componentType
                          - status
                          - time
                        properties:
                          componentType:
                            type: string
                          status:
                            type: string
                            enum: [PASS, FAIL, WARN]
                          time:
                            type: string
                            format: date-time
                          observedValue:
                            type: number
                          observedUnit:
                            type: string

Implementation Considerations ​

  1. Caching: Consider caching health check results for a short period (e.g., 5-10 seconds) to reduce load on backend systems.
  2. Partial Health: Implement a way to report partial health status when some components are degraded but the API is still operational.
  3. Monitoring Integration: Ensure the health check endpoint can be easily integrated with monitoring and alerting systems.
  4. Rate Limiting: Apply rate limiting to the health check endpoint to prevent potential abuse.

References ​