Hail API

At the core of Hail is the API, which powers our own JavaScript application - and it's also available for public use. The API is REST-oriented, meaning the API endpoints act as resources in the Hail domain, which are operated on using actions, facilitated by HTTP verbs such as GET and POST.

Endpoint

The root of the Hail API is at https://hail.to/api. We are currently on the first version (v1) of the API, so most resources will be prefixed as such.

Authentication

Hail implements OAuth 2 for authentication. You can read more in the OAuth article.

Error Handling

Any error that happens in an API call will be presented as a JSON response to the request as follows:

{
    "error": {
        "message": "An English error message here",
        "error_code": null
    }
}

Note that error_code is a Hail-specific code which explains the problem in more detail in the documentation, and may be null. This is different from the HTTP status code which indicates the general nature of the response (whether it be error or success). We do not currently make use of this field, so it will always be null.

General Status Codes

In the spirit of REST, we issue semantic status codes to convey the outcome of a request to the Hail API. Most of the expected status codes can be found in the specific call's documentation, however there are some general status codes that you'll need to handle.

400 Bad Request	The request body failed validation for resource create and update actions.
401 Not Authenticated	You tried to access an authenticated resource without a valid access token
403 Forbidden	The currently authenticated user is not allowed to access the requested resource
404 Not Found	The resource you tried to address doesn't exist
405 Method Not Allowed	The HTTP verb used is not valid for the resource
429 Too Many Requests	Rate limit for the API exceeded
500 Internal Server Error	There was some fatal problem on the server side. We are automatically alerted to these and will be investigating
503 Service Unavailable	The API is temporarily down for maintenance or overloading

A note on backwards compatibility

We will not make backwards-incompatible changes to the API on a publicly released version. If we need to make such a change, we will bump the API up to a new version, say 1.1, for that endpoint.

However, we could add fields or change the ordering of existing fields in API responses. Therefore, you should not rely on the ordering or number of fields in the JSON payloads. You should access the JSON fields by name, not by their position, and your app shouldn't break if we add new fields.