{"_id":"55ed06c7023a81170018f163","parentDoc":null,"user":"55d2bd8e2463351700f67dd7","category":{"_id":"55e67b5dde6fef23009480ca","__v":20,"pages":["55ed06c7023a81170018f163","55ed079b0d968e2100de8339","55ed0b530d968e2100de8345","55ed0bb078319821005005cf","55ed0df94fba582b0036a18a","55ed0e0c4fba582b0036a18d","55ed0ebd8da0b12100e64246","55ed10bec9d5b3350072ae9a","55ed11410d968e2100de834d","55ed118678319821005005d9","55ed121dc9d5b3350072ae9e","55ed12de8da0b12100e6424e","55ed13930d968e2100de8352","55ed140c4fba582b0036a196","55ed1902c9d5b3350072aebb","55ed197bc9d5b3350072aec0","55ee3dba1452cd0d009e5ee9","5600a22f0c703d19009531e1","5600c6b23aa0520d00da0c41","561da674e078f40d00eadd75"],"project":"55e67aaa9cc7c62b00c4a1ea","version":"55e67aab9cc7c62b00c4a1ed","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-09-02T04:30:21.948Z","from_sync":false,"order":5,"slug":"rest-api","title":"REST API"},"project":"55e67aaa9cc7c62b00c4a1ea","__v":10,"version":{"_id":"55e67aab9cc7c62b00c4a1ed","project":"55e67aaa9cc7c62b00c4a1ea","__v":10,"createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z","categories":["55e67aac9cc7c62b00c4a1ee","55e67b5556007d23005fee7d","55e67b5dde6fef23009480ca","55e680efde6fef23009480db","55e6829485a9741900314e99","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","589b8e1fdbb7cd190026732c","58b8ca5e3265d70f001788d4"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":["5853256974e2070f000c1ff5"],"next":{"pages":[],"description":""},"createdAt":"2015-09-07T03:38:47.886Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":0,"body":"The Carnival REST API allows you to get Analytics, send Messages and Notifications and update Devices.\n\n\n## Getting an API Key\nTo register an API, Login to Carnival and navigate to Settings, Developer, Integrations. Click *Create API Client*. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/5278faf-Screen_Shot_2017-02-28_at_7.08.21_PM.png\",\n        \"Screen Shot 2017-02-28 at 7.08.21 PM.png\",\n        642,\n        461,\n        \"#d2d9da\"\n      ],\n      \"caption\": \"Creating an API Client with Carnival\"\n    }\n  ]\n}\n[/block]\nYou can specify an IP address to restrict access to the API. API Clients can be registered through the Carnival Mobile Platform, and can have either or both of these permissions:\n\n * Analytics access\n * Push notification service access\n \nIf 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.\n\n\n## Authentication\nAuthentication is performed over HTTP basic Auth.  There is no requirement for a username, however, you must use your API Client key as the password.\n\nFor testing in the browser you can use the built-in browser dialog box which will prompt you for these credentials when you first make a request against the API.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/l2Xk5UMREmU0ZSTfHOXb_Screen%20Shot%202015-08-26%20at%203.00.21%20pm.png\",\n        \"Screen Shot 2015-08-26 at 3.00.21 pm.png\",\n        \"400\",\n        \"168\",\n        \"#09bc5f\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n## Default parameters\n * APIs with with time range responses (Analytics) will default to a one month window.\n\n## Rate limits\nWe suggest you send no more than 40 requests/second. Please contact us if you need to increase this limit.\n\n## Handling 500 and 503 responses\n\nWhen 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.\n\n**Recommended best practices**\n\n* **Log appropriately** <br \\>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](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) if possible), Request Method, Request URL, Request Header, Request Body, Response Status Code and Response Body Text. <br \\><br \\>A logged message might look like:\n```\n[unique_id] Timestamp: \"2017-01-31T13:12:05Z\"\n[unique_id] Request_Method: \"POST\"\n[unique_id] Request_URL: \"api.carnivalmobile.com/events\"\n[unique_id] Request_Headers: 'Content-Type': 'application/json' \n[unique_id] Request_Body: { \"name\": \"example\", \"count\": 3 }\n[unique_id] Response_Code: 500 \n[unique_id] Response_Body: \"An internal server error was encountered processing your request\"\n```\n\n* **Retry 503s** <br \\>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](https://en.wikipedia.org/wiki/Exponential_backoff) to give the request you are retrying the best possible chance of success. <br \\><br \\>Also see Microsoft Azure's article on [retry best practices](https://docs.microsoft.com/en-us/azure/best-practices-retry-general)\n\n* **Report if occurrences of 50x errors persist** <br \\>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.\n\n## Get Started!\nHere are some of the APIs you can start with:\n * [Notifications](doc:notifications) \n * [Devices](doc:devices) \n * [Users](doc:users) \n * [Audience](doc:audience) \n * [Audiences](doc:audiences) \n * [Stats / Active Users](doc:active-users) \n * [Stats / Installs](doc:installs) \n * [Stats / Total Installs](doc:total-installs) \n * [Stats / Opens](doc:opens) \n * [Stats / Opens](doc:opens) \n * [Stats / Geography](doc:geography) \n * [Stats / Time In App](doc:time-in-app)\n * [Stats / Technology](doc:technology) \n * [Stats / In-app Messages](doc:message-stats) \n * [Stats / Push Notifications](doc:push-notification-stats)","excerpt":"","slug":"api-getting-started","type":"basic","title":"Getting Started"}
The Carnival REST API allows you to get Analytics, send Messages and Notifications and update Devices. ## Getting an API Key To register an API, Login to Carnival and navigate to Settings, Developer, Integrations. Click *Create API Client*. [block:image] { "images": [ { "image": [ "https://files.readme.io/5278faf-Screen_Shot_2017-02-28_at_7.08.21_PM.png", "Screen Shot 2017-02-28 at 7.08.21 PM.png", 642, 461, "#d2d9da" ], "caption": "Creating an API Client with Carnival" } ] } [/block] You can specify an IP address to restrict access to the API. API Clients can be registered through the Carnival 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. For testing in the browser you can use the built-in browser dialog box which will prompt you for these credentials when you first make a request against the API. [block:image] { "images": [ { "image": [ "https://files.readme.io/l2Xk5UMREmU0ZSTfHOXb_Screen%20Shot%202015-08-26%20at%203.00.21%20pm.png", "Screen Shot 2015-08-26 at 3.00.21 pm.png", "400", "168", "#09bc5f", "" ] } ] } [/block] ## Default parameters * APIs with with time range responses (Analytics) will default to a one month window. ## Rate limits We suggest you send no more than 40 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** <br \>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](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) if possible), Request Method, Request URL, Request Header, Request Body, Response Status Code and Response Body Text. <br \><br \>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** <br \>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](https://en.wikipedia.org/wiki/Exponential_backoff) to give the request you are retrying the best possible chance of success. <br \><br \>Also see Microsoft Azure's article on [retry best practices](https://docs.microsoft.com/en-us/azure/best-practices-retry-general) * **Report if occurrences of 50x errors persist** <br \>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. ## Get Started! Here are some of the APIs you can start with: * [Notifications](doc:notifications) * [Devices](doc:devices) * [Users](doc:users) * [Audience](doc:audience) * [Audiences](doc:audiences) * [Stats / Active Users](doc:active-users) * [Stats / Installs](doc:installs) * [Stats / Total Installs](doc:total-installs) * [Stats / Opens](doc:opens) * [Stats / Opens](doc:opens) * [Stats / Geography](doc:geography) * [Stats / Time In App](doc:time-in-app) * [Stats / Technology](doc:technology) * [Stats / In-app Messages](doc:message-stats) * [Stats / Push Notifications](doc:push-notification-stats)