Stability policy

This is the promise the HTTP API makes to a client that is already working.

What may ship at any time

Additive changes — new endpoints, new optional fields, new statuses on existing endpoints — may ship at any time, without notice.

Write clients that tolerate them:

• Ignore fields you do not recognise. Do not fail on an unexpected key in a JSON object, and do not validate responses against a closed schema.
• Branch on the status codes you know, and treat the rest by class: any other 4xx is a client mistake worth failing loudly on, any 5xx is worth retrying.
• Do not depend on the order of a list beyond what the contract states, or on the exact text of an error string. Branch on the status code; the text is for a human reading a log.

What requires a new prefix

A change that removes or renames a field, changes what an existing status means, or otherwise breaks a working client requires a new path prefix — /v2/ — and the prefix it replaces keeps working for six months.

There is no version header and no version query parameter. The path is the version.

What this covers

The policy covers everything documented in the HTTP API contract and the API reference.