The Engage by Sailthru Mobile REST API allows you to get Analytics, send Messages and Notifications and update Devices.
Get an API Key
To register an API, Login to Engage by Sailthru Mobile and navigate to Settings, Developer, Integrations. Click Create API Client.
You can specify an IP address to restrict access to the API. API Clients can be registered through the Engage by Sailthru Mobile Platform, and can have either or both of these permissions:
- 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.
- 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
When calling any remote web API you will encounter Internal Server Error (500) or Service Unavailable (503) errors from time to time. While we do our upmost to minimise occurrences of these errors, we cannot remove them entirely as they can often occur for reasons out of our control. Therefore we recommend the following best practices for minimising the impact of 50x errors. Recommended best practices
- 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.
