Getting Started
Contents
The Sailthru Mobile REST API allows you to get Analytics, send Messages and Notifications and update Devices.
- Analytics access
- Push notification service access
If you send a request to an API endpoint the API Client key doesn't have permissions for, you will receive a 403 HTTP Response code.
Authentication
Authentication is performed over HTTP basic Auth. There is no requirement for a username, however, you must use your API Client key as the password.
Default Perameters
- APIs with with time range responses (Analytics) will default to a one month window.
Rate Limits
We suggest you send no more than 120 requests/second. Please contact us if you need to increase this limit.
Handling 500 and 503 Responses
- Log appropriately
When making an API call expect that a 50x error could occur and ensure you log the output. We recommend as a minimum logging: Date and time of occurrence (in UTC if possible), Request Method, Request URL, Request Header, Request Body, Response Status Code and Response Body Text.
A logged message might look like:
[unique_id] Timestamp: "2017-01-31T13:12:05Z" [unique_id] Request_Method: "POST" [unique_id] Request_URL: "api.carnivalmobile.com/events" [unique_id] Request_Headers: 'Content-Type': 'application/json' [unique_id] Request_Body: { "name": "example", "count": 3 } [unique_id] Response_Code: 500 [unique_id] Response_Body: "An internal server error was encountered processing your request"
- Retry 503s Very occasionally a service could be unavailable for a short period of time. It is safe to retry a failed request when encountering a 503, although it is wise to cap the amount of retries to a sensible figure. Consider utilising a cool-down period or exponential back-off to give the request you are retrying the best possible chance of success. Also see Microsoft Azure's article on retry best practices
- Report if occurrences of 50x errors persist If you are encountering a high number of 500s over a reasonable period of time please contact our support department. Providing as much logged information as possible will give us the best chance to resolve any issues quickly.