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
.
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...
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.
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 astate
key containing the most recent state in the room, whereas the new/sync
API\'sstate
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 thesince
token than thelimit
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 theprev_batch
token as a reference to obtaining more.- The
state
contained in the response to a/sync
request that has asince
parameter will contain only keys that have changed since the basis given in thesince
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.
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