119 lines
4.5 KiB
Markdown
119 lines
4.5 KiB
Markdown
+++
|
|
title = "Migrating from Client Server API v1"
|
|
aliases = ["/docs/guides/migrating-from-client-server-api-v-1"]
|
|
+++
|
|
|
|
This guide assists developers of API clients that target the `v1` version of the
|
|
API to migrate their code to the later `r0`. It does not aim to introduce new
|
|
concepts that were added in `r0` except where these replace things that were
|
|
removed since `v1`.
|
|
|
|
## Updated Version In Path
|
|
|
|
The new version of the API is `r0`; this should be used in paths where `v1` used
|
|
to appear. Additionally, the `/api` path component has now been removed. API
|
|
endpoint paths are now:
|
|
|
|
```
|
|
POST /_matrix/client/r0/register
|
|
GET /_matrix/client/r0/login
|
|
```
|
|
|
|
etc...
|
|
|
|
## New Registration and Login Endpoints
|
|
|
|
The `r0` version of the `/register` and `/login` endpoints is different to the
|
|
`v1` version. See the updated API documentation for details on how the new API
|
|
works. In brief, the changes are that the new version returns extra information
|
|
in the form of the `params` object, and that a sequence of multiple calls may
|
|
be statefully chained together by the `session` parameter.
|
|
|
|
Additionally, whereas in `v1` the client performed a `GET` request to discover
|
|
the list of supported flows for `/register`, in `r0` this is done by sending a
|
|
`POST` request with an empty data body. The `/login` endpoint continues to use
|
|
the `GET` method as before.
|
|
|
|
## Deprecated Endpoints
|
|
|
|
The following endpoints are now deprecated and replaced by the `/sync` API:
|
|
|
|
```
|
|
/initialSync
|
|
/events
|
|
/rooms/:roomId/initialSync
|
|
```
|
|
|
|
The new `/sync` API takes an optional `since` parameter to distinguish the
|
|
initial sync from subsequent updates for more events.
|
|
|
|
The return value takes a different structure to that from the previous
|
|
`/initialSync` API. For full details see the API documentation, but the
|
|
following summary may be useful to compare with `v1`:
|
|
|
|
> - `/initialSync` returned a `state` key containing the most recent
|
|
> state in the room, whereas the new `/sync` API's `state`
|
|
> corresponds to the room state at the start of the returned
|
|
> timeline. This makes it easier for clients to represent state
|
|
> changes that occur within the region of returned timeline.
|
|
> - In `/events`, if more events occurred since the `since` token than
|
|
> the `limit` parameter allowed, then events from the start of this
|
|
> range were returned and the client had to perform another fetch to
|
|
> incrementally obtain more of them. In the `/sync` API the result
|
|
> always contains the most recent events, creating a gap if this
|
|
> would be more events than the requested limit. If this occurs then
|
|
> the client can use the `prev_batch` token as a reference to
|
|
> obtaining more.
|
|
> - The `state` contained in the response to a `/sync` request that
|
|
> has a `since` parameter will contain only keys that have changed
|
|
> since the basis given in the `since` parameter, rather than
|
|
> containing a full set values.
|
|
|
|
The `/initialSync` API allowed a parameter called `limit` to limit the number of
|
|
events returned. To apply this limit to the new `/sync` API, you can supply an
|
|
ad-hoc filter:
|
|
|
|
```
|
|
GET .../sync?filter={"room":{"timeline":{"limit:$limit}}}
|
|
```
|
|
|
|
There is no direct replacement for the per-room `/rooms/:roomId/initialSync`
|
|
endpoint, but the behaviour can be recreated by applying an ad-hoc filter using
|
|
the `filter` parameter to `/sync` that selects only the required room ID:
|
|
|
|
```
|
|
GET .../sync?filter={"room":{"rooms":[$room_id]}}
|
|
```
|
|
|
|
However, the way that the new `/sync` API works should remove any need to do
|
|
this kind of query, in the situations where the `v1` API needed it.
|
|
Specifically, on joining a new room the initial information about that room is
|
|
sent in the next `/sync` batch, so it should not be necessary to query that one
|
|
room specially.
|
|
|
|
The following endpoint is deprecated and has no direct replacement:
|
|
|
|
```
|
|
/events/:eventId
|
|
```
|
|
|
|
However, if the client knows the room ID of the room that the event is in, it
|
|
can use the `/rooms/:roomId/context/:eventId` request to fetch the event
|
|
itself. By giving the `limit` parameter of `0` the client can save using extra
|
|
bandwidth by actually returning additional context events around the requested
|
|
one.
|
|
|
|
## Removed POST Endpoint
|
|
|
|
The room message sending API endpoint in `v1` accepted both `PUT` and `POST`
|
|
methods, where the client could specify a message ID in the `PUT` path for
|
|
de-duplication purposes, or have the server allocate one during `POST`. In `r0`
|
|
this latter form no longer exists. Clients will now have to generate these IDs
|
|
locally.
|
|
|
|
The following URLs have therefore been removed:
|
|
|
|
```
|
|
POST .../rooms/:roomId/send/:messageType
|
|
```
|