Versioning & deprecation
The API version is part of the URL. Within a version, changes are additive and backward-compatible; anything that could break you waits for a new version.
Version in the path
The current version is v1, carried as a path prefix on
every endpoint — https://api.uat.trailblazertech.com/v1/....
When a future incompatible version is introduced it will live under a new
prefix (/v2), and v1 will keep working during a published
overlap period.
What can change within v1 (non-breaking)
Treat the following as expected, backward-compatible changes. Build your integration to tolerate them:
- New endpoints and new optional request parameters or body fields.
- New fields added to a response object. Ignore fields you don't recognize rather than failing on them.
- New optional response types or headers.
- New enum values in places already documented as open-ended.
The error-code set is a deliberate
exception: it is closed and will not gain new code values
within v1. You can switch over it exhaustively (while still handling an
unexpected value defensively).
What waits for a new version (breaking)
- Removing or renaming an endpoint, field, or enum value.
- Changing a field's type or making an optional field required.
- Changing the meaning of an existing field or status.
- Tightening validation in a way that rejects previously valid requests.
Deprecation policy
When something in v1 is slated for removal in a future version:
- It is announced in the changelog before it changes.
- The affected part continues to function for the duration of the announced notice period.
- When a successor version ships, v1 remains available through the overlap period stated in that announcement so you have time to migrate.
Keep an eye on the changelog, and always build clients that ignore unknown response fields — that single habit protects you from the great majority of forward changes.