EOAP OpenAPI Health Check

EOAP OpenAPI Health Check provides a shared contract for reporting the health of EOAP services and their dependencies. The contract follows the application/health+json Internet-Draft and exposes it as an OpenAPI 3.1 definition for a conventional GET /health endpoint.

The OpenAPI definition is the source of truth. It is used to generate:

• Pydantic models, published on PyPI as eoap-api-health-check;
• a rendered OpenAPI reference for the project documentation; and
• a reusable API contract for services and tooling in any language.

What the contract describes

A health response has one of three outcomes:

• pass (including the compatible aliases ok and up) for a healthy service;
• warn for a service that remains available but has concerns; or
• fail (including error and down) for an unhealthy service.

Responses can include service metadata, diagnostic notes, links, and checks grouped by dependency or sub-component. Each check can report an observed value, its unit, the observation time, affected endpoints, and diagnostic output.

See the project documentation for the design and usage overview, or inspect the OpenAPI source for the complete contract.

Install the Python models

pip install eoap-api-health-check

The generated models can be used to construct and validate health payloads:

from eoap_api_health_check import ComponentHealth, HealthyResponse, HealthyStatus

health = HealthyResponse(
    status=HealthyStatus.PASS,
    version="1.0.0",
    checks={
        "database:responseTime": [
            ComponentHealth(
                componentType="datastore",
                observedValue=42,
                observedUnit="ms",
                status=HealthyStatus.PASS,
            )
        ]
    },
)

payload = health.model_dump(by_alias=True, mode="json", exclude_none=True)

Property names in Python use snake_case; passing aliases such as componentType is also supported. Serializing with by_alias=True produces the camel-cased names defined by the wire format.

FastAPI integration

Since version 0.3.0, an optional FastAPI extension provides the HealthJSONResponse convenience response. Install it with:

pip install "eoap-api-health-check[fastapi]"

Use the response in a route to serialize a health model as application/health+json and add a default Cache-Control: max-age=60 header:

from fastapi import FastAPI

from eoap_api_health_check import HealthyResponse
from eoap_api_health_check.fastapi import HealthJSONResponse

app = FastAPI()


@app.get("/health", response_class=HealthJSONResponse)
def health() -> HealthJSONResponse:
    return HealthJSONResponse(
        HealthyResponse(
            status="pass",
            version="1.0.0",
            service_id="catalogue-api",
        )
    )

Pass status_code or cache_control to customize the HTTP response. Set cache_control=None to omit the cache header.

Development

Do not edit src/eoap_api_health_check/__init__.py directly: it is regenerated from schemas/openapi.yaml.

With Task installed, run the complete generation and validation workflow with:

task

Useful focused tasks are:

task process_schema         # regenerate the Pydantic models
task generate_openapi_docs  # refresh the documentation artifacts
task serve_docs             # build and serve the documentation locally

License

This project is licensed under the Apache License 2.0.