Skip to content

API Reference

health(conditions, *, success_handler=default_handler, failure_handler=default_handler, success_status=200, failure_status=503)

Create a health check route.

Parameters:

Name Type Description Default
conditions List[Callable[..., Dict[str, Any] | bool]]

A list of callables that represents the condition of your service.

 required
success_handler Callable[..., Awaitable[dict]]

A callable which receives the conditions results, and returns a dictionary that will be the content response of a successful health call.

 default_handler
failure_handler Callable[..., Awaitable[dict]]

A callable analogous to success_handler for failure scenarios.

 default_handler
success_status int

An integer that overwrites the default status (200) in case of success.

 200
failure_status int

An integer that overwrites the default status (503) in case of failure.

 503

Returns:

Type Description
Callable[..., Coroutine[None, None, JSONResponse]]

Callable[..., Awaitable[JSONResponse]]: The health check route.
Source code in fastapi_health/route.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def health(
    conditions: List[ConditionFunc],
    *,
    success_handler: Callable[..., Awaitable[dict]] = default_handler,
    failure_handler: Callable[..., Awaitable[dict]] = default_handler,
    success_status: int = 200,
    failure_status: int = 503,
) -> Callable[..., Coroutine[None, None, JSONResponse]]:
    """Create a health check route.

    Args:
        conditions (List[Callable[..., Dict[str, Any] | bool]]): A list of callables
            that represents the condition of your service.
        success_handler (Callable[..., Awaitable[dict]]): A callable which receives
            the `conditions` results, and returns a dictionary that will be the content
            response of a successful health call.
        failure_handler (Callable[..., Awaitable[dict]]): A callable analogous to
            `success_handler` for failure scenarios.
        success_status (int): An integer that overwrites the default status (`200`) in
            case of success.
        failure_status (int): An integer that overwrites the default status (`503`) in
            case of failure.

    Returns:
        Callable[..., Awaitable[JSONResponse]]: The health check route.
    """

    async def endpoint(**dependencies) -> JSONResponse:
        if all(dependencies.values()):
            handler = success_handler
            status_code = success_status
        else:
            handler = failure_handler
            status_code = failure_status

        output = await handler(**dependencies)
        return JSONResponse(jsonable_encoder(output), status_code=status_code)

    params = []
    for condition in conditions:
        params.append(
            Parameter(
                f"{condition.__name__}",
                kind=Parameter.POSITIONAL_OR_KEYWORD,
                annotation=bool,
                default=Depends(condition),
            )
        )
    endpoint.__signature__ = Signature(params)
    return endpoint