Versioning

The v1 promise - additive changes only - and how a breaking change would be announced.

Everything under /v1 keeps working as documented. Within v1, changes are additive: new operations, new optional parameters, new fields in answers, new error codes, new event types. Write clients that ignore fields they do not know.

A change that could break a client (a removed field, a changed meaning) only happens in a new version (/v2), or, if it must happen in v1, with at least 6 months' notice: a Deprecation and a Sunset header on the affected operation and an entry in the Changelog.

Limits and weights are not part of the version: they may change with notice in the Changelog.