HealthCheck

An endpoint that returns 200/500 to denote if backend services are functional.

1. Overview
2. dependency_injection_names
3. classes_to_build
4. callables
5. description
6. url
7. request_methods

Overview

You can provide dependency injection names, classes, or a callable. When invoked, this endpoint will build/call all of them and, as long as none raise any exceptions, return a 200.

HealthCheck endpoints are always public and ignore authentication/authorization settings.

If you don’t provide any configuration to the endpoint, it will always succeed:

import clearskies

wsgi = clearskies.contexts.WsgiRef(
    clearskies.endpoints.HealthCheck(),
)
wsgi()

which when invoked:

$ curl 'http://localhost:8080' | jq
{
    "status": "success",
    "error": "",
    "data": {},
    "pagination": {},
    "input_errors": {}
}

This example demonstrates a failed healthcheck by requesting the cursor (which attempts to connect to the database). Since no database has been setup/configured, it always fails:

import clearskies

wsgi = clearskies.contexts.WsgiRef(
    clearskies.endpoints.HealthCheck(
        dependency_injection_names=["cursor"],
    ),
)
wsgi()

And when invoked returns:

$ curl 'http://localhost:8080' | jq
{
    "status": "failure",
    "error": "",
    "data": {},
    "pagination": {},
    "input_errors": {}
}

with a status code of 500.

dependency_injection_names

Optional

A list of dependency injection names that should be fetched when the healthcheck endpoint is invoked.

If any exceptions are raised when building the dependency injection parameters, the health check will return failure.

classes_to_build

Optional

A list of classes to build with the dependency injection system.

The If any exceptions are raised when building the classes, then the healthcheck will return a failure. In the following example, since the class-to-build requests the cursor, and we don’t have a reachable database configured,

import clearskies

class MyClass:
    def __init__(self, cursor):
        pass

wsgi = clearskies.contexts.WsgiRef(
    clearskies.endpoints.HealthCheck(
        classes_to_build=[MyClass],
    ),
)
wsgi()

callables

Optional

A list of callables to invoke.

Your callables can request any dependency injection names. If any exceptions are raised, the healthcheck will return a failure. The return value from the function is ignored. In this example we request the cursor from the dependency injection system, which will call the healthcheck to fail since we don’t have a database setup and configured:

import clearskies

def my_function(cursor):
    pass

wsgi = clearskies.contexts.WsgiRef(
    clearskies.endpoints.HealthCheck(
        callables=[my_function],
    ),
)
wsgi()

description

Optional

A description for this endpoint. This is added to any auto-documentation

url

Optional

Set the URL for the endpoint

When an endpoint is attached directly to a context, then the endpoint’s URL becomes the exact URL to invoke the endpoint. If it is instead attached to an endpoint group, then the URL of the endpoint becomes a suffix on the URL of the group. This is described in more detail in the documentation for endpoint groups, so here’s an example of attaching endpoints directly and setting the URL:

import clearskies

endpoint = clearskies.endpoints.Callable(
    lambda: {"hello": "World"},
    url="/hello/world",
)

wsgi = clearskies.contexts.WsgiRef(endpoint)
wsgi()

Which then acts as expected:

$ curl 'http://localhost:8080/hello/asdf' | jq
{
    "status": "client_error",
    "error": "Not Found",
    "data": [],
    "pagination": {},
    "input_errors": {}
}

$ curl 'http://localhost:8080/hello/world' | jq
{
    "status": "success",
    "error": "",
    "data": {
        "hello": "world"
    },
    "pagination": {},
    "input_errors": {}
}

Some endpoints allow or require the use of named routing parameters. Named routing paths are created using either the /{name}/ syntax or /:name/. These parameters can be injected into any callable via the routing_data dependency injection name, as well as via their name:

import clearskies

endpoint = clearskies.endpoints.Callable(
    lambda first_name, last_name: {"hello": f"{first_name} {last_name}"},
    url="/hello/:first_name/{last_name}",
)

wsgi = clearskies.contexts.WsgiRef(endpoint)
wsgi()

Which you can then invoke in the usual way:

$ curl 'http://localhost:8080/hello/bob/brown' | jq
{
    "status": "success",
    "error": "",
    "data": {
        "hello": "bob brown"
    },
    "pagination": {},
    "input_errors": {}
}

request_methods

Optional

The allowed request methods for this endpoint.

By default, only GET is allowed.

import clearskies

endpoint = clearskies.endpoints.Callable(
    lambda: {"hello": "world"},
    request_methods=["POST"],
)

wsgi = clearskies.contexts.WsgiRef(endpoint)
wsgi()

And to execute:

$ curl 'http://localhost:8080/' -X POST | jq
{
    "status": "success",
    "error": "",
    "data": {
        "hello": "world"
    },
    "pagination": {},
    "input_errors": {}
}

$ curl 'http://localhost:8080/' -X GET | jq
{
    "status": "client_error",
    "error": "Not Found",
    "data": [],
    "pagination": {},
    "input_errors": {}
}