API versioning

changelog.d/1-api-changes/api-versioning

@@ -0,0 +1,30 @@
+Start version 2 of the public API. Main changes:
+
+ - Asset endpoints have lost their `v3` and `v4` suffixes. So for example
+   `/assets/v3` has been replaced by `/assets`.
+ - `GET /conversations/:conv/assets/:id` and `GET
+   /conversations/:conv/otr/assets/:id` have been removed.
+ - `GET /assets/:key/v3` has been removed. Use the qualified endpoint `GET
+   /assets/:domain/:key` instead.
+ - `DELETE /assets/:key/v3` has been removed. Use the qualified endpoint
+   `DELETE /assets/:domain/:key` instead.
+ - `GET /connections` has been removed. Use `POST /list-connections` instead.
+ - `POST /connections` has been removed. Use `POST /connections/:domain/:user` instead.
+ - `PUT /connections/:domain/:user` has been removed: use `POST` instead.
+ - `GET /conversations` has been removed. Use `POST /conversations/list-ids`
+   followed by `POST /conversations/list` instead.
+ - `POST /conversations/list/v2` has been replaced by `POST
+   /conversations/list`.
+ - `POST /conversations/:domain/:conv/members/v2` has lost its `v2` suffix, so
+   it is now `POST /conversations/:domain/:conv/members`.
+ - `GET /users`, `GET /users/by-handle` and `GET /users/handles` have been
+   removed. Use `POST /search/contacts` instead.
+ - `GET /users/:id` has been removed. Use the qualified endpoint `GET
+   /users/:domain/:id` instead.
+ - `GET /users/:id/clients` has been removed. Use the qualified endpoint `GET
+   /users/:domain/:id/clients` instead.
+ - `GET /users/:id/clients/:client` has been removed. Use the qualified
+   endpoint `GET /users/:domain/:id/clients/:client` instead.
+
+Swagger documentation for the previous version of the API can be accessed at
+`/v1/api/swagger-ui`.

changelog.d/1-api-changes/development-version

@@ -0,0 +1,8 @@
+A new field `development` has been added to the object returned by `GET
+/api-version`. Versions listed there are considered in flux, meaning that the
+corresponding API contracts can change arbitrarily over time. Clients are free
+to use development versions, as long as they are also listed in `supported`,
+and failures due to incompatibilities are acceptable (e.g. in testing
+environments). Backends are the authoritative source on whether a development
+version can be used at all. If a development version should not be used, the
+backend will not list it among the supported versions at all.

changelog.d/6-federation/api-versioning

@@ -0,0 +1 @@
+We now fetch version information from other backends and negotiate a version to use.