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