Versioning

The Version is in the path: /v1.

Within a Version, the API only grows

An Additive Change can arrive in v1 at any time, with no notice:

• a new endpoint
• a new optional request parameter
• a new field in a response
• a new value in a list of values that the docs call open

Ignore a response field that you do not know. A client that fails on a new field will break.

A Breaking Change needs a new Version

A Breaking Change arrives only in a new Version, such as /v2:

• a field or an endpoint that goes away, or gets a new name
• a new required request parameter
• a field that changes its type
• validation that becomes stricter

We check every change to the API against the published contract before it ships. A Breaking Change to v1 does not pass that check.

The contract

The API reference is made from the same definitions as the API itself. It cannot show an endpoint that the API does not have.