From 313fdab8489bc377883384a7c2e6593f41f69fe1 Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Thu, 14 Apr 2016 16:15:46 +0100 Subject: [PATCH 01/12] Initial hack at migration guide --- .../client-server-migrating-from-v1.rst | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 supporting-docs/howtos/client-server-migrating-from-v1.rst diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst new file mode 100644 index 00000000..7674c1e0 --- /dev/null +++ b/supporting-docs/howtos/client-server-migrating-from-v1.rst @@ -0,0 +1,69 @@ +Migrating from client-server API v1 +=================================== + +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``. + +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. + +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. These return data in a +different format. + +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. + +See the new API documentation for details on the new return +value. + +The following endpoint is deprecated and has no direct replacement:: + + /events/:eventId + +However, if the client is aware of the room ID 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 + +Updated Version In Path +======================= + +The new version of the API is ``r0``; this should be used in paths where +``v1`` appears:: + + POST /_matrix/client/api/r0/register + GET /_matrix/client/api/r0/login + etc... From 96577cffd7c5382e242b83326f413e23cb34f4d1 Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Thu, 14 Apr 2016 16:56:35 +0100 Subject: [PATCH 02/12] Also no /api path component any more --- supporting-docs/howtos/client-server-migrating-from-v1.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst index 7674c1e0..4b9111fb 100644 --- a/supporting-docs/howtos/client-server-migrating-from-v1.rst +++ b/supporting-docs/howtos/client-server-migrating-from-v1.rst @@ -62,8 +62,9 @@ Updated Version In Path ======================= The new version of the API is ``r0``; this should be used in paths where -``v1`` appears:: +``v1`` appears. Additionally, the ``/api`` path component has now been removed. +API endpoint paths are now:: - POST /_matrix/client/api/r0/register - GET /_matrix/client/api/r0/login + POST /_matrix/client/r0/register + GET /_matrix/client/r0/login etc... From 55a9d0b06723d25e0c6d00e6ff76abf30f61396d Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Thu, 14 Apr 2016 17:00:56 +0100 Subject: [PATCH 03/12] login®ister flow discovery by empty POST --- supporting-docs/howtos/client-server-migrating-from-v1.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst index 4b9111fb..504c32a4 100644 --- a/supporting-docs/howtos/client-server-migrating-from-v1.rst +++ b/supporting-docs/howtos/client-server-migrating-from-v1.rst @@ -15,6 +15,10 @@ 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 can perform a ``GET`` request to +discover the list of supported flows, in ``r0`` this is done by sending a +``POST`` request with an empty data body. + Deprecated Endpoints ==================== From 4f5ae82be9ba86c9975aca5601b060cc0c54c6a9 Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Thu, 14 Apr 2016 17:21:44 +0100 Subject: [PATCH 04/12] Actually it's only /register that discovers flows by empty POST; /login uses GET --- supporting-docs/howtos/client-server-migrating-from-v1.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst index 504c32a4..276be655 100644 --- a/supporting-docs/howtos/client-server-migrating-from-v1.rst +++ b/supporting-docs/howtos/client-server-migrating-from-v1.rst @@ -16,8 +16,9 @@ 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 can perform a ``GET`` request to -discover the list of supported flows, in ``r0`` this is done by sending a -``POST`` request with an empty data body. +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 ==================== From a0de12f24ed8e78e13df0cc34c4eed7a0f2fe626 Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Thu, 14 Apr 2016 18:35:49 +0100 Subject: [PATCH 05/12] More detail on using /sync with ad-hoc filters --- .../howtos/client-server-migrating-from-v1.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst index 276be655..807f0988 100644 --- a/supporting-docs/howtos/client-server-migrating-from-v1.rst +++ b/supporting-docs/howtos/client-server-migrating-from-v1.rst @@ -31,14 +31,18 @@ The following endpoints are now deprecated and replaced by the ``/sync`` API:: The new ``/sync`` API takes an optional ``since`` parameter to distinguish the initial sync from subsequent updates for more events. These return data in a -different format. +different format. Instead of the ``limit`` parameter, supply an ad-hoc filter +that provides the required event count:: + + 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. +the ``filter`` parameter to ``/sync`` that selects only the required room ID:: -See the new API documentation for details on the new return -value. + GET .../sync?filter={"room":{"rooms":[$room_id]}} + +See the new API documentation for details on the new return value. The following endpoint is deprecated and has no direct replacement:: From 29f675e3c65033e98d73014ab3f80d941914db47 Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Tue, 19 Apr 2016 16:13:17 +0100 Subject: [PATCH 06/12] Remark that per-room /sync probably isn't necessary these days --- .../howtos/client-server-migrating-from-v1.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst index 807f0988..5f1450bc 100644 --- a/supporting-docs/howtos/client-server-migrating-from-v1.rst +++ b/supporting-docs/howtos/client-server-migrating-from-v1.rst @@ -36,13 +36,19 @@ that provides the required event count:: GET .../sync?filter={"room":{"timeline":{"limit:$limit}}} +See the new API documentation for details on the new return value. + 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]}} -See the new API documentation for details on the new return value. +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:: From 46341b226933f20feeb7be32a6418ccdc0feb7c6 Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Tue, 19 Apr 2016 17:29:59 +0100 Subject: [PATCH 07/12] Add some notes about the main differences in return value of /sync as compared /initialSync --- .../client-server-migrating-from-v1.rst | 22 ++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst index 5f1450bc..f725b7cf 100644 --- a/supporting-docs/howtos/client-server-migrating-from-v1.rst +++ b/supporting-docs/howtos/client-server-migrating-from-v1.rst @@ -36,7 +36,27 @@ that provides the required event count:: GET .../sync?filter={"room":{"timeline":{"limit:$limit}}} -See the new API documentation for details on the new return value. +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``: + + * The ``/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. + + * Additionally, the ``state`` contained in the ``/sync`` response by default + only contains keys that have changed since the basis given in the ``since`` + parameter, rather than containing a full set values. + + * In ``/initialSync`` if the requested range contains more events than the + ``limit`` parameter allows, then events from the start of this range were + returned and the client must perform another fetch to incrementally obtain + more of them. In the ``/sync`` API the result always contains the end of the + requested range (i.e. the most recent events); possibly creating a gap. If + this occurs then the client can use the ``prev_batch`` token as a reference + to obtaining more. 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 From 98df455a99b4b27d1c6e4048e3ae6616c9419aed Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Tue, 19 Apr 2016 17:44:48 +0100 Subject: [PATCH 08/12] Refer to old v1 behaviours in past-tense for clarity of reading --- .../howtos/client-server-migrating-from-v1.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst index f725b7cf..796a420d 100644 --- a/supporting-docs/howtos/client-server-migrating-from-v1.rst +++ b/supporting-docs/howtos/client-server-migrating-from-v1.rst @@ -15,7 +15,7 @@ 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 can perform a ``GET`` request to +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. @@ -30,9 +30,8 @@ The following endpoints are now deprecated and replaced by the ``/sync`` API:: /rooms/:roomId/initialSync The new ``/sync`` API takes an optional ``since`` parameter to distinguish the -initial sync from subsequent updates for more events. These return data in a -different format. Instead of the ``limit`` parameter, supply an ad-hoc filter -that provides the required event count:: +initial sync from subsequent updates for more events. Instead of the ``limit`` +parameter, supply an ad-hoc filter that provides the required event count:: GET .../sync?filter={"room":{"timeline":{"limit:$limit}}} @@ -97,8 +96,8 @@ Updated Version In Path ======================= The new version of the API is ``r0``; this should be used in paths where -``v1`` appears. Additionally, the ``/api`` path component has now been removed. -API endpoint paths are now:: +``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 From 54624f397ad07fc63e896a0d9a6655b9d195d0ac Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Tue, 19 Apr 2016 18:26:01 +0100 Subject: [PATCH 09/12] Clarification/rewording on old and new sync-with-limit behaviour --- .../howtos/client-server-migrating-from-v1.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst index 796a420d..8e8e2b02 100644 --- a/supporting-docs/howtos/client-server-migrating-from-v1.rst +++ b/supporting-docs/howtos/client-server-migrating-from-v1.rst @@ -49,13 +49,13 @@ following summary may be useful to compare with ``v1``: only contains keys that have changed since the basis given in the ``since`` parameter, rather than containing a full set values. - * In ``/initialSync`` if the requested range contains more events than the - ``limit`` parameter allows, then events from the start of this range were + * 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 must perform another fetch to incrementally obtain - more of them. In the ``/sync`` API the result always contains the end of the - requested range (i.e. the most recent events); possibly creating a gap. If - this occurs then the client can use the ``prev_batch`` token as a reference - to obtaining more. + more of them. In the ``/sync`` API the result always contains up to the most + recent event; 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. 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 From 8f22cf6cb889e9769d38777d75005635515306a9 Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Wed, 20 Apr 2016 14:59:38 +0100 Subject: [PATCH 10/12] Minor rewording/grammar --- .../howtos/client-server-migrating-from-v1.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst index 8e8e2b02..d96daa1d 100644 --- a/supporting-docs/howtos/client-server-migrating-from-v1.rst +++ b/supporting-docs/howtos/client-server-migrating-from-v1.rst @@ -51,11 +51,11 @@ following summary may be useful to compare with ``v1``: * 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 must perform another fetch to incrementally obtain - more of them. In the ``/sync`` API the result always contains up to the most - recent event; 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. + 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. 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 From ea6ac3e40fd65fcfa35d1be5ebd11d584f2ad42c Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Wed, 20 Apr 2016 15:04:23 +0100 Subject: [PATCH 11/12] Another rewording of 'state' returned by '/sync' with 'since' parameter --- .../howtos/client-server-migrating-from-v1.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst index d96daa1d..5633d387 100644 --- a/supporting-docs/howtos/client-server-migrating-from-v1.rst +++ b/supporting-docs/howtos/client-server-migrating-from-v1.rst @@ -45,10 +45,6 @@ following summary may be useful to compare with ``v1``: for clients to represent state changes that occur within the region of returned timeline. - * Additionally, the ``state`` contained in the ``/sync`` response by default - only contains keys that have changed since the basis given in the ``since`` - parameter, rather than containing a full set values. - * 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 @@ -57,6 +53,11 @@ following summary may be useful to compare with ``v1``: requested limit. If this occurs then the client can use the ``prev_batch`` token as a reference to obtaining more. + * Additionally, the ``state`` contained in the ``/sync`` response that has a + ``since`` parameter will contains only keys that have changed since the + basis given in the ``since`` parameter, rather than containing a full set + values. + 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:: From a077f8470ae9b38ba9d41e07370a91236637b033 Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Thu, 21 Apr 2016 17:23:04 +0100 Subject: [PATCH 12/12] Various rewordings from latest review comments --- .../client-server-migrating-from-v1.rst | 59 ++++++++++--------- 1 file changed, 31 insertions(+), 28 deletions(-) diff --git a/supporting-docs/howtos/client-server-migrating-from-v1.rst b/supporting-docs/howtos/client-server-migrating-from-v1.rst index 5633d387..a8c8db48 100644 --- a/supporting-docs/howtos/client-server-migrating-from-v1.rst +++ b/supporting-docs/howtos/client-server-migrating-from-v1.rst @@ -6,6 +6,17 @@ 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 ==================================== @@ -30,22 +41,19 @@ The following endpoints are now deprecated and replaced by the ``/sync`` API:: /rooms/:roomId/initialSync The new ``/sync`` API takes an optional ``since`` parameter to distinguish the -initial sync from subsequent updates for more events. Instead of the ``limit`` -parameter, supply an ad-hoc filter that provides the required event count:: - - GET .../sync?filter={"room":{"timeline":{"limit:$limit}}} +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``: - * The ``/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. + * ``/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 + * 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 @@ -53,11 +61,17 @@ following summary may be useful to compare with ``v1``: requested limit. If this occurs then the client can use the ``prev_batch`` token as a reference to obtaining more. - * Additionally, the ``state`` contained in the ``/sync`` response that has a - ``since`` parameter will contains only keys that have changed since the + * 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:: @@ -74,11 +88,11 @@ The following endpoint is deprecated and has no direct replacement:: /events/:eventId -However, if the client is aware of the room ID 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. +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 ===================== @@ -92,14 +106,3 @@ to generate these IDs locally. The following URLs have therefore been removed:: POST .../rooms/:roomId/send/:messageType - -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...