Metadata-Version: 2.4
Name: eoap-api-health-check
Version: 0.4.0
Summary: EOAP HTTP API Health Check
Project-URL: Documentation, https://eoap.github.io/api-health-check/
Project-URL: Issues, https://github.com/eoap/api-health-check/issues
Project-URL: Source, https://github.com/eoap/api-health-check
Author-email: Fabrice Brito <info@terradue.com>, Simone Tripodi <info@terradue.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: pydantic==2.13.4
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.140.0; extra == 'fastapi'
Description-Content-Type: text/markdown

# EOAP OpenAPI Health Check

[![PyPI - Version](https://img.shields.io/pypi/v/eoap-api-health-check.svg)](https://pypi.org/project/eoap-api-health-check)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/eoap-api-health-check.svg)](https://pypi.org/project/eoap-api-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](https://datatracker.ietf.org/doc/html/draft-inadarei-api-health-check-06)
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](https://eoap.github.io/api-health-check/) for
the design and usage overview, or inspect the
[OpenAPI source](schemas/openapi.yaml) for the complete contract.

## Install the Python models

```console
pip install eoap-api-health-check
```

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

```python
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:

```console
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:

```python
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](https://taskfile.dev/) installed, run the complete generation and
validation workflow with:

```console
task
```

Useful focused tasks are:

```console
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](https://www.apache.org/licenses/LICENSE-2.0).
