Versioning¶
Two version numbers¶
You will see two, and they mean different things.
| Example | Changes when | |
|---|---|---|
| API version — in the path | /v2/projects |
A breaking change ships. Rarely. |
| Service version — in the reference | v1.0.62 |
Every release. Often. |
They are unrelated
The badge at the top of /reference currently reads
v1.0.62. That is the deployed service release, not API version 1.
The API you call is v2. A service version beginning 1. alongside a /v2
path is expected, not a mistake.
Only the path version is a contract. The service version tells you which build is deployed, which is useful when reporting a problem and otherwise safe to ignore.
Version 2 is current¶
Version 2 is current. Version 1 still serves traffic but is legacy: it is absent from the reference and will not receive new endpoints.
Moving from v1 to v2¶
- Change the prefix to
/v2 - Obtain a bearer token — see Authentication
- Send
Authorization: Bearer <token>on every request - Handle
403— v2 authorises every request against your role, which v1 did not do
It is not only a prefix change
Several v2 endpoints return a different representation from their v1 counterpart, and some return different fields depending on your role. Check each endpoint in /reference rather than assuming parity.
What counts as breaking¶
The policy is stated in /reference; the practical consequence for a client is that additive changes arrive without warning. New fields, new endpoints and new optional parameters can all appear within a major version.
So a client that rejects unknown response fields will break on a change that was never meant to affect it. Ignore what you do not recognise.