/v1, apart from API key management.
The release version, for example 0.1.0, is info.version in the
OpenAPI spec, and each release is listed in the
changelog.
Changes that ship inside /v1
These are additive. They can arrive in any release with no notice, so write clients that tolerate them:- New endpoints.
- New optional request fields and query parameters.
- New fields in responses, including inside
error.details. - New values in open ended codes:
warnings[].code,details.reason,details.venue_codeandstatus_reason.code. - New venues in order and preview
legs,balancesandpositions.
Breaking changes
A breaking change removes or renames a field, changes a field’s type or meaning, makes an optional field required, or changes the HTTP status orerror.code of an existing case.
- During the 0.x preview, a breaking change can still ship inside
/v1. Each one is listed in the changelog with the date it takes effect, and announced ahead of that date whenever possible. - From 1.0, breaking changes ship only in a new path version such as
/v2.
Deprecation
Removing an endpoint or field starts with a deprecation notice. It is removed at least 90 days after the notice, never sooner. The notice is given in two places:- An entry in the changelog naming what is deprecated, what replaces it, and the removal date.
DeprecationandSunsetheaders on every response from the affected endpoint.Sunsetis the removal date. Watch for both headers in your client logs.