Versioning

Version 1

The API is version 1. Every path starts with /api/v1, and every JSON answer a route in the reference gives to a successful request carries schemaVersion: 1.

Within v1, changes only add

A change within v1 adds something, and takes nothing away:

• new routes;
• new optional fields in a request;
• new fields in an answer;
• new values in a field whose description says it can have more, such as owner.type in GET /whoami.

Nothing is removed or renamed, and schemaVersion stays 1.

So your client must ignore what it doesn’t know. A field it doesn’t recognize can appear anywhere in an answer: skip it, and never fail on it. Read it leniently shows this for the bundle.

A breaking change is a new version

A change that does more than add ships only as a new version of the API, at /api/v2.

Where changes are announced

Changes are announced in the changelog.