How to Implement an API Readiness Endpoint

An API readiness endpoint is an HTTP endpoint used by infrastructure to determine if an application can receive traffic. Misconfigured readiness handling can lead to new instances receiving traffic prematurely, unavailable instances continuing to receive traffic, healthy instances being removed from traffic, and repeated checks causing overload of failing dependencies.

To implement an API readiness endpoint, track the application's state (starting, ready, or shutting down), expose a dedicated endpoint (e.g., GET /ready) that returns HTTP 200 OK when ready and HTTP 503 Service Unavailable otherwise. Configure the infrastructure to periodically call the endpoint and route traffic only to applications reporting as ready.

Create a singleton class to keep track of the application's state, with methods to get the current state and update it. Mount the readiness endpoint after lightweight observability middleware, but before authentication, validation, business logic, or middleware that may fail for unrelated reasons.

Verify the health of each dependency that, if failing, would prevent the application from serving traffic. For example, if PostgreSQL is required for request processing, return HTTP 503 Service Unavailable if PostgreSQL is unavailable. Perform lightweight dependency checks that do not cause side effects, such as executing a SELECT 1 query.

Run independent dependency checks concurrently to prevent response time accumulation and ensure the endpoint responds within the probe timeout. Apply a short timeout to each check to prevent slow or unresponsive dependencies from blocking the endpoint's response.