Using the API
Learn how to use the Roastify API.
The Roastify API is a REST (RESTful) based API that uses generic HTTP for communication. The API is designed to have predictable, resource-oriented URLs, with responses in JSON format.
Endpoint
All requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. The base URL for all API requests is:
Versioning
Roastify uses a versioning scheme to indicate which version of the API is being used. The current version is v1. The version is specified in the URL path, e.g. /v1/....
Rate Limiting
Rate limiting occurs on the edge, with very minimal performance penalty (typically around 0.1ms). Requests are rate limited to 100 requests per minute.
Errors
Roastify uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
- Codes in the
2xxrange indicate success - Codes in the
4xxrange indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.) - Codes in the
5xxrange indicate an error with Roastify’s servers (these should be rare)
Authentication
Roastify uses API keys to authenticate requests. More documentation on this can be found here.
Pagination
Requests that return multiple items will be paginated to 20 items by default. The API uses cursor-based pagination which gives users the flexibility to specify a pageSize parameter to control the number of items per page. Additionally, users can provide a cursor parameter to retrieve results starting from a specific point in the dataset.
Currency
All monetary values are represented in the currency’s smallest unit (cents). For example, 2400 represents $24.00 in USD. This is to avoid any unwanted rounding errors when dealing with currency. We express this as an integer to avoid floating point precision issues.
At the moment, Roastify only accepts USD.