How to connect to the Erin API
The following section details how to connect to our API.
Once we have agreed to you having access to the system, we will send you the following:
- A url to give you access to an appropriate test system
- An api key you can use as a bearer token
Message format
The system uses Json messaging carried over the HTTP protocol for all its requests and responses, the messages are stateless. We validate all input data you send us both in terms of its validity and length so please do not be surprised if you find we are strict in terms of the content matching our expectations. If your message is valid save for a validation infringement you will receive an error message telling you what is wrong with your request.
- In general you can expect the following:
- Information requests such as airport lists are handled via HTTP Get messages
- Action messages such as make a booking are handled via an HTTP message
Authentication
To secure our API we use a token, this token governs which of our API methods are available to you, who you are, what channel you are allocated for pricing and which client account your bookings should be stored in.
Tokens are the predominant type of access token used globally to secure API access. A token is an opaque string, not intended to have any meaning to clients using it. Some servers will issue tokens that are a short string of hexadecimal characters, while others may use structured tokens such as JSON Web Tokens.
The token we use reflect that policy in that it is an opaque string of characters.
The token we provide will give you access to the test system alone, it will not give you access to live systems, a new token will be provided once you have completed your development.
To utilise the token please add a header to the request, named x-api-key with a value of the authorisation token we provide, without this value access to the API will be denied with a '403' error.
Request headers
Like most systems we expect a series of headers to be set on each request, they are as follows:
| Header | Value |
|---|---|
| Content-Type | application/json |
| Content-Length | Calculated length of request |
| Accept | application/json |
| Accept-Encoding | gzip, deflate, br |
| x-api-key | {authorisation key} |
HTTP status and errors
The success of the message and the HTTP status are distinct from each other, a request can be successful in HTTP terms and yet unsuccessful in action terms
You can broadly expect three HTTP status values from our system except in exceptional circumstances:
- 200 - Indicates a success, the underlying message should be examined to determine success
- 403 - Unauthorised - you are not authorised to use this message
- 429 - You have exceeded the maximum number of requests we allow you to send per minute, please cease sending messages and retry after 1 minute
Rate limiting
You will have noticed above that we may respond with an HTTP status of 429 if you exceed a defined rate limit. If you feel the limit assigned to you is too low, please contact us, and we will be happy to discuss it with you, although we usually defer the response to the client you are connecting to as they pay for the traffic you generate.