API overview

This guide provides an overview of ROLLER's different APIs and best practices.

APIs

ROLLER has two APIs as follows:

• Data API
  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 you to query specific records, and returns paginated data for a time period. It is optimized for periodic export of records on an hourly or daily frequency.
  
  More information: Data API
  
  
• Rest API
  The Rest API is a general-purpose API which supports live use cases and enables the creation of ROLLER bookings.

General concepts

API documentation can be found at https://docs.roller.app 

Authentication

ROLLER APIs use an OAuth2 flow whereby the consuming app uses its client id and client secret from ROLLER 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, go to API authentication.

Scope

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, go to 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.

Rate limiting

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. 

Create API credentials in ROLLER

After subscribing to API access with ROLLER, you can create API credentials to link ROLLER's public API with an external application by following these steps:

1. From Venue Manager, go to Settings > Integrations > API Keys
2. Select Create client key on the top left of the screen
3. 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"
     
     
4. Select the Create button.

Enter the client ID and client secret ID into the appropriate fields in the external application's account. If you're not sure where, contact the provider's support team. Learn more about the integrations that ROLLER currently connects with