Versioning
Know which API changes can reach your integration inside /v1 and how to write a client that keeps working.
The API is versioned by URL prefix. Everything published so far lives under /v1, which is the only prefix in use. There is no version header, no date pinning and nothing to configure.
What can change inside /v1
/v1 changes additively:
- New endpoints can be added.
- New response fields can be added to existing responses.
- New response headers can be added.
X-Skipped-KeysandX-Missing-Source-KeysonGET /v1/pullwere added this way, rather than by changing the file body.
A field you already parse does not change shape and does not disappear. If a change cannot be made additively, it ships under a new version prefix, and /v1 keeps working.
Writing a client that keeps working
Additive changes are only safe for a client that expects them:
| Do | Because |
|---|---|
| Ignore JSON fields you do not recognise | New fields are added to existing responses |
| Ignore headers you do not recognise | New headers are added the same way |
Branch on a problem's type, and fall back to its status for a type you do not know | New endpoints can bring problem types of their own |
Handle an unknown value in a field such as a batch's status or a webhook's event instead of failing | A client that degrades on the unexpected keeps running while you update it |
Never parse detail | It is a sentence for a person and its wording can change |
| Subscribe webhooks to the events you handle, by name | A new event never reaches an endpoint that did not subscribe to it |
type Batch = { id: number; status: string; total: number; completed: number; failed: number };
function isFinal(batch: Batch): boolean {
switch (batch.status) {
case 'pending':
case 'processing':
return false;
case 'completed':
case 'completed_with_errors':
case 'failed':
case 'cancelled':
return true;
default:
// A status this client does not know yet. Log it and keep polling.
console.warn(`Unknown batch status ${batch.status}`);
return false;
}
}Deprecations and the changelog
Every change to /v1 is recorded in the API changelog, dated, separately from product releases. Its deprecation register lists every published surface with the release that shipped it. Nothing has been deprecated or removed: the removal column reads "none scheduled" for every row. A removal would appear there with a date long before it happened, and the row would stay in the table afterwards.