One of design goal is that anyone with familiarity with RESTful JSON APIs before should find themselves the experience intuitive.
Before building an integration, read our recommendations and notes.
API versioning
As system changes can be costly and time-consuming, the Orderful platform is designed with stability and longevity in mind.
Any changes made to the API which are breaking will be expressed with a new version number. Versions can be seen in the first segment of an endpoint, for example:
GET <https://api.orderful.com/v2/transactions> - denotes the version is v2
Version Changes
Versions support additive changes, i.e. adding new properties. This makes it important to configure JSON parsers to allow for additional elements.
Within a version, Orderful may add data to an API contract. For example following endpoint and payload
GET <https://api.orderful.com/v2/example>
{
"name": "Frank",
"employeeId": 123
}
The following would not be considered a breaking change
GET <https://api.orderful.com/v2/example>
{
"name": "Frank",
"employeeId": 123,
"hiredAt": "01-01-2020"
}
See more information about versioning here
Rate Limits
All Orderful API endpoints documented in this API Reference are rate limited.
Endpoints may have different limits based on their use case and complexity. All rate limits can be seen by looking at the response header. It will include the following
x-ratelimit-limit - Maximum number of requests per minute interval
x-ratelimit-remaining - Number of requests allowable in the current minute interval
x-ratelimit-reset - Time until the interval resets
If you exceed a limit, you will receive an HTTP 429 status code back from Orderful. The HTTP 429 will also include a Retry-After header. This header will specify the number of seconds you need to wait until you retry your request.
For example, on an endpoint with a 100 req/min limit if you were to make 100 requests within 30 seconds, your 101st request would return this:
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
Retry-After: 30
Handling Rate Limit Violations
Your integration should have logic that is able to handle this response code and resend the request after the specified number of seconds.
Use 64-bit integers for IDs when parsing numbers
Some entities in our platform come in high quantities, you'll want to be prepared for some big numbers. Program defensively and use the appropriate data type.