Working with the API
Versioning
v1 only ever grows. Anything that would break an integration ships as v2, and v1 keeps working.
What can change inside v1
The version is in the path: https://api.ordexs.com/v1. Inside v1, changes are additive only:
- new endpoints;
- new fields on objects and in responses;
- new optional request fields and query parameters;
- new event types;
- new values in an enum, such as a new order status;
- new error codes.
Write your integration to tolerate all of these:
- Ignore fields you don't know. Don't fail on an unexpected key in a response or a webhook.
- Treat an unknown enum value as the closest one you know. An unknown order status should be handled like
pending. - Don't subscribe to every event by default; subscribe to the ones you handle.
What never changes inside v1
Renaming or removing a field, changing its type, making an optional field required, or changing what an existing code means. Those changes need v2, and v1 keeps running alongside it.
Every response carries an Ordexs-Version header with the date of the contract it follows, for your logs.
Staying informed
Every change is listed, newest first, in the changelog. The full contract is always available as an OpenAPI 3.1 file.
