HTTP requests must have a Content-Type header with the value “application/json”.
HTTP responses will always use application/json as Content-Type.
As is implicit with this content type, the content encoding used in both requests and responses is UTF-8.
Bookeo accounts can support multiple client languages. Names and descriptions of products, resources, options, categories, etc. can also be provided by the account manager in multiple languages.
To specify the desired language for an API invocation, the application can add a HTTP request parameter “lang“. Language tags are expressed using RFC 5646 notation. For example: “lang=en-US”.
To obtain a list of customer languages supported for the account, call the /settings/languages API endpoint. If the requested language tag is not in the list of customer languages supported for the account, an error response will be returned.
To request Bookeo to use the default language tag for customers, as set in the account’s preferences, use “lang=customerDefault” as parameter.
To request Bookeo to use the default language tag for users, as set in the account’s preferences, use “lang=userDefault” as parameter.
If no lang parameter is specified, Bookeo will assume “userDefault”.
In any case, Bookeo will always include a HTTP header “Content-Language” in the response, specifying the language tag used in the response.
The secret key and API key must be included in every invocation.
They can be passed either as request parameters in the URL (“secretKey” and “apiKey”) or as HTTP request headers (“X-Bookeo-secretKey” and “X-Bookeo-apiKey”).
If an error occurs during an API invocation, a non-success HTTP status code will be set for the response.
The response content will be a JSON object containing a more descriptive error message, and an error id. If contacting our tech support about an error, make sure to always quote the error id provided.
Example of error response:
HTTP/1.1 403 Forbidden
Date: Tue, 31 Mar 2015 00:49:22 GMT
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Cache-Control: private, max-age=0, no-cache, no-store
Pragma: no-cache
Content-Language: en-US
Content-Type: application/json
Content-Length: 151
{
"httpStatus": 403,
"message": "The maximum number of children for a booking for \u0027Tour 2\u0027 is 0",
"errorId": "1907D150331004922CHCTM"
}Note how the HTTP status is reported again in the response entity body, in addition to the normal status of the HTTP response.
The API reference will specify, for each endpoint, the HTTP status code returned in case of a successful invocation.
Bookeo uses the format for dates and times specified by RFC 3339.
Fields and parameters marked as being of type “date-time” in the API reference documentation are expressed in the RFC’s date-time format. Example:
2016-12-19T16:39:00-08:00
Fields and parameters marked as being of type “date” in the API reference documentation are expressed in the RFC’s full-date format. Example:
2016-12-19
For date-time values returned by Bookeo, the partial-time part indicates the time of an event in the account’s local time zone. The offset can be used to convert the time to UTC, and from there to any other time zone.
For example when querying the start time of a tour, Bookeo may return a value like 2016-03-10T08:00:00+11:00, which means that:
Depending on requirements, the application can decide to display the local time, or to use the time-offset to convert it to any other time zone.
Also when sending date-time values as fields or request parameters to Bookeo, an application can use the special time-offset “-00:00” to indicate “the time expressed is intended in the account’s local timezone, whatever that is”. Any other time-offset will have the usual meaning as per RFC.
Some API responses may return lists of many JSON objects. To limit the size of a single response, and network traffic in general, Bookeo uses pagination to split long lists in multiple “pages” of results.
API endpoints that return paginated results are described in the API reference documentation. These methods always return data in this format:
{
"data": [
… items …
],
"info": {
"totalItems": 500,
"totalPages": 5,
"currentPage": 1,
"pageNavigationToken": "xDgBr3m8qxLWtkSA"
}
}To navigate to another page, an application can simply invoke the same API endpoint again, passing only two parameters, pageNavigationToken and pageNumber (apart from apiKey and secretKey, which are always required unless you use the alternative request headers). Any other parameter will be ignored.
The pageNavigationToken to use would be the one found in the original response.
The pageNumber is the number of the page to retrieve. The index of the first page is 1, the index of the last page is in the “totalPages” field of the info element returned.
For example to navigate to the last page of the above paginated result:
https://api.bookeo.com/v2/…?pageNavigationToken=xDgBr3m8qxLWtkSA&pageNumber=5
The number of items per page can be specified in the initial call (within limits described in the reference documentation). If not specified, a default value will be used. The default for each endpoint is specified in the reference documentation.
If the results of an API invocation can fit in a single page, there will be no pageNavigationToken in the response, as page navigation is not necessary.
Example:
{
"data": [
… 60 items …
],
"info": {
"totalItems": 60,
"totalPages": 1,
"currentPage": 1,
}
}It is recommended to cache some of the API invocation results, to improve response times to users and reduce number of API invocations. For example the list of languages, the name of products available, the list of people categories are good candidates for caching, as they rarely change.
Bookeo applies dynamic throttling to API requests, to prevent excessive traffic to degrade overall performance. Throttling is applied at the account level, so the traffic generated by ALL applications installed for an account is measured as one. When traffic for an account is temporarily blocked, ALL applications trying to invoke the API on the behalf of that account will be blocked. Please note Bookeo may permanently block an app that continues to exceed traffic limits so it is important to check for these error responses and take appropriate remedial action.
When an API invocation is rejected because of throttling, the HTTP response status code will be 429 (“Too Many Requests”), and a corresponding “Retry-After” HTTP header will be included in the response. The value of this HTTP header is the number of seconds after which the application can re-submit the request.
Example of error response in case API traffic for an account is throttled:
HTTP/1.1 429 Too Many Requests
Date: Tue, 31 Mar 2015 01:03:48 GMT
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Cache-Control: private, max-age=0, no-cache, no-store
Pragma: no-cache
Retry-After: 23
Content-Length: 153
{
"httpStatus": 429,
"message": "Traffic limits exceeded. Please try again in 23 seconds.",
"retryAfter": 23,
"errorId": "85A150331120349NU4A7"
}