EOAP OpenAPI Health Check

EOAP OpenAPI Health Check defines a consistent, machine-readable way for EOAP services to describe their operational health. It gives service implementers, platform operators, monitoring systems, and client applications a common contract instead of requiring each service to invent its own health payload.

The project is based on the application/health+json Internet-Draft. That draft defines the representation; this project supplies an OpenAPI 3.1 description and uses the conventional /health path as an implementation choice.

Purpose

The contract is intended to make health information portable across EOAP components. A producer can return a predictable payload, while a consumer can validate and interpret that payload without depending on service-specific response shapes.

The OpenAPI definition supports two complementary use cases:

• API integration. Services in any language can implement the documented GET /health operation and use the schema to validate responses or generate client code.
• Python integration. Pydantic models generated from the same definition are published to PyPI as eoap-api-health-check, allowing Python services to construct and validate compatible payloads directly.

The OpenAPI file is therefore the source of truth. Generated Python models and rendered documentation are delivery formats of the same contract, not separate definitions to maintain by hand.

Health representation

Every response contains a required status. The supported outcomes are:

The aliases make it easier to integrate services that already expose common framework conventions, including Node Terminus and Spring Boot terminology.

A response may also contain:

• version, releaseId, and serviceId to identify the running service and release;
• description, notes, and output to provide human-readable context;
• links to related resources; and
• checks with observations about dependencies or internal sub-components.

Checks are grouped under keys such as database:responseTime. Each key maps to an array so that a logical component can report observations for one or more instances. An observation can include a component identifier and type, an observed value and unit, its own status, a timestamp, affected API endpoints, diagnostic output, and related links.

{
  "status": "warn",
  "version": "1.0.0",
  "notes": ["Database latency is elevated"],
  "checks": {
    "database:responseTime": [
      {
        "componentType": "datastore",
        "observedValue": 900,
        "observedUnit": "ms",
        "status": "warn",
        "time": "2026-07-22T10:00:00Z"
      }
    ]
  }
}

Using the Python package

Install the generated Pydantic models from PyPI:

pip install eoap-api-health-check

Then create or validate a response using the models exported by eoap_api_health_check:

from eoap_api_health_check import ComponentHealth, WarnResponse

health = WarnResponse(
    notes=["Database latency is elevated"],
    checks={
        "database:responseTime": [
            ComponentHealth(
                componentType="datastore",
                observedValue=900,
                observedUnit="ms",
                status="warn",
            )
        ]
    },
)

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

The models use idiomatic snake_case Python attributes and accept the camel-cased OpenAPI property names as aliases. Use by_alias=True when serializing a response for the API.

FastAPI integration

Since version 0.3.0, the package includes an optional FastAPI extension with a HealthJSONResponse convenience response. Install the FastAPI extra:

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

The response accepts a HealthyResponse, WarnResponse, or UnhealthyResponse, serializes it with the OpenAPI property aliases, serves it as application/health+json, and adds Cache-Control: max-age=60 by default:

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",
        )
    )

The optional status_code argument changes the HTTP status. Use cache_control to provide another caching policy, or set it to None to omit the header.

Project artifacts

• OpenAPI definition — the complete API and schema contract.
• Rendered OpenAPI reference — an interactive view generated from the definition.
• Python package — generated Pydantic models for Python applications.
• Source repository — schema, generation workflow, and project history.

Changes should begin in schemas/openapi.yaml in the source repository. The Pydantic models and documentation artifacts are regenerated from it before a new package version is published.