Using the 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:

https://api.roastify.app/v1/

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 penality (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 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Roastify's servers (hopefully these are 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. This allows for efficient navigation through large result sets while maintaining data integrity and consistency.

"https://api.roastify.app/v1/orders?pageSize=50&cursor=clpy8pn3e0201fd72krv36u80"

The API will return the following pagination object in the response if the query permits cursor pagination:

"pageInfo": {
    "endCursor": "clpy8pn3e0201fd72krv36u80",
    "hasNextPage": true
}

Zero-decimal 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.