Versioning

Every path starts with /v1. Within v1, the API only changes in ways that keep existing clients working. A breaking change would be a /v2, served beside /v1.

Compatible changes

These can happen at any time within v1:

• a new resource or operation;
• a new optional parameter;
• a new field in an object;
• a new value in an enumeration;
• a new error code;
• a different order of the fields;
• a different length or format of ids and tokens.

What never changes within v1

• A field, a parameter, a path, an enumeration value or an error code is never renamed, retyped or removed.
• An optional parameter never becomes required.
• A default never changes, such as the default limit or the order of lists.

Writing a client that keeps working

• Ignore fields you do not know. Do not fail when an object has one more field.
• Accept enumeration values you do not know. A status can gain a value; give it a neutral treatment rather than an error.
• Accept error codes you do not know. Act on the HTTP status and the error type.
• Do not depend on ids. Store them as opaque strings, without assuming a length or a pattern.

Stable shapes

A field is always present: null when it has no value, [] for an empty list. The exceptions are total_count and the fields lists leave out by default, which appear only when you ask for them. Enumeration values are lowercase, and dates are Unix timestamps in seconds, UTC.

Staying informed

Every change is listed in the changelog, with its date.