Working with the API
Versioning.
What can change in v1 and what never will, and how to write code that keeps working as the API grows.
The version is in every path: /v1. Everything you build on v1 keeps working for as long as v1 exists.
What v1 may add#
v1 only grows. Within it, we may add:
- new endpoints and new events;
- new optional fields in what you send;
- new fields in what we answer;
- new values in a list of values, like a new order status or a new error code.
So read answers loosely: ignore fields you do not know, and treat an unknown value as "something else" rather than an error. The SDKs already do both: an unknown field is kept aside and an unknown value is kept as it came.
What v1 never does#
- remove or rename a field;
- change a field's type, unit or meaning;
- make an optional field required, or refuse something it accepted;
- change the error code of a situation.
Anything that needs one of these waits for a v2, which will run beside v1 for a long time before v1 ends.
Seeing the version#
GET /v1 answers the exact version of the API (1.MINOR.PATCH), and so does info.version in the OpenAPI document. The SDKs' major version is the API's: every SDK 1.x speaks /v1.