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
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. See more in Consuming Responses