Health Checks

Clients can check the health of any AIR service by calling:

HEAD /health/status

GET /health/status

Health of the service should only be determined by inspecting the http status code returned.

The HTTP method HEAD should be used in preference to GET wherever possible.

Expected HTTP status codes

The /health/status endpoints can return the following HTTP status codes:

HTTP Status Code	HTTP Status Description	RAG	Note
200	OK	Green
400	Bad Request	Green
401	Unauthorized	Green	not yet implemented
405	Method Not Allowed	Green
429	Too Many Requests	Green	not yet implemented
500	Internal Server Error	Red
502	Server Error	Red	text/html response only
503	Service Unavailable	Amber	A "Retry-After" header will also be returned

A 502 status code can be returned after prolonged return of a 500 status code from the public /health/status endpoint, and will be accompanied by a body in text/html format.

Interpretation of HTTP status codes

The returned status code should be interpreted as per the RAG column value below:

RAG	Interpretation	Action
Red	the service is unavailable	No requests should be made at this time. Check health again in 60 seconds
Amber	the service is available	Non-essential requests should not be made at this time. Use the "Retry-After" header in the response to determine how many seconds to wait before calling again
Green	the service is available	Make requests as required, within permitted limits

Response format

The default response will be in application/json format and encoded using UTF-8. The format can be overridden by sending the HTTP "Accept" header, with one of the following values:

Accept Header	Note
application/json	default for all status codes (except 502)
text/html	the only format available for 502
text/plain
text/xml

A response body will only be present for GET requests.

Response encoding

The default response will be uncompressed. To request a compressed response, send the "Accept-Encoding" header, with one of the values gzip or deflate, or both:

Accept-Encoding	Note
gzip	gzip accepted by client
deflate	deflate accepted by client
gzip, deflate	either gzip or deflate accepted by client

Example requests

POS and Wallet health checks are shown below for the UK environments:

curl -I https://pos.uk.eagleeye.com/health/status

curl -I https://wallet.uk.eagleeye.com/health/status

The examples above are for the UK. Please replace uk within the URLs with the territory specific country code as appropriate. Please use the appropriate sub-domain for other services.

Force a specific response

To aid with integration testing, clients can force a specific response to be returned with:

HEAD /health/status/`{200|400|401|405|429|500|502|503}`

The following example will force the response to be 502:

curl -I https://wallet.uk.eagleeye.com/health/status/502

Detailed examples

Human/machine readable response - for information only

The textual response is subject to change without notice and should not be parsed by programs in order to determine health.

$ curl https://pos.sandbox.uk.eagleeye.com/health/status

{
    "summary": {
        "status": "GREEN",
        "message": "Our service is currently working as expected"
    },
    "detail": {
        "environment": "sandbox-uk",
        "reason": "Normal response",
        "requestId": "XkWq4jpXHFZ@jWfTjvO7gwAAACU"
    }
}

Machine readable response - for health determination

Health of the service should only be determined by inspecting the http status code returned.

curl -sI -o /dev/null -w "%{http_code}" https://pos.sandbox.uk.eagleeye.com/health/status