Versioning
What can change under /v1, and what cannot.
The version is in the path: /v1. Within it we add, and we do not break.
We may, without notice:
- add endpoints, optional request fields, and response fields;
- add values to fields documented as open lists, such as stream names;
- improve error
messagewording.
We will not, within /v1:
- remove or rename a field, endpoint or error code;
- change a field's type or meaning;
- make an optional request field required.
Write clients that ignore fields they do not recognise. The SDKs do.
Breaking changes get a new path, /v2, with /v1 kept running alongside it and a
deprecation date announced well ahead.