This article provides an overview of ROLLER's different API's and best practices.
ROLLER has two API's as follows:
The purpose of the API is to provide venues with a mechanism to extract ROLLER data and syndicate that data to an external database, business intelligence or analytics platform. It does not provide any ability to write data to ROLLER.
This API should not be used for real-time data use cases as it does not allow to query specific records and returns paginated data for a time period. It is optimised for periodic export of records on an hourly or daily frequency.
More information - Data API.
The Rest API is a general-purpose API which supports live use cases and enables the creation of ROLLER bookings.
API documentation can be found at https://docs.roller.app
ROLLER API's use an OAuth2 flow whereby the consuming app uses their client id and client secret to request an access token from the /token endpoint. It is this access token that is used in calls to API endpoints
The access token is short-lived - its expiry is provided in the token response and may change from time to time. Therefore consumer apps should always reuse the current token until they receive a 401 (Unauthorised) response from any endpoint at which time they should request a new token.
Do not request a new token for each API call.
This may result in a 429 (Too many requests) response and result in the suspension of your API credentials/access.
For more information regarding the authentication endpoint - API authentication.
The scope of a set of API credentials (client id and client secret) is limited to a single venue. If you have multiple ROLLER venues you must create separate sets of credentials for each venue. For more information regarding creating API credentials - API Access.
A set of credentials will enable the consumer app to access both the production and playground environment endpoints as per information regarding - Environments.
Each set of API credentials are limited to one API call per second.
Therefore we do not recommend sharing a set of API credentials between multiple consumer apps as for multiple consumers/apps as this may result in a 429 (Too many requests) response.
To create a set of API credentials:
- Login to ROLLER Venue Manager
- Navigate to Settings > Integrations > API Keys
- Click Create client key on the top left of the screen
- A pop-up window will be displayed
- Select to create API Key or Gate Server Key from the toggle options
- Enter a description to the Client key name field which describes the consumer app that these credentials will be allocated to - for example Data warehouse app
- Click the Create button.