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/17] 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/17] 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/17] 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/17] 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/17] 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:: + + GET .../sync?filter={"room":{"rooms":[$room_id]}} -See the new API documentation for details on the new return -value. +See the new API documentation for details on the new return value. The following endpoint is deprecated and has no direct replacement:: From c67c35061197bf088a0a3aa0c497e3ae07abc547 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 16 Apr 2016 22:46:47 +0100 Subject: [PATCH 06/17] spell out that Matrix is more concerned with bridging than XMPP --- supporting-docs/guides/2015-08-19-faq.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/supporting-docs/guides/2015-08-19-faq.md b/supporting-docs/guides/2015-08-19-faq.md index 2bbfff17..6c388717 100644 --- a/supporting-docs/guides/2015-08-19-faq.md +++ b/supporting-docs/guides/2015-08-19-faq.md @@ -226,6 +226,8 @@ drove us in this direction were: FMUC improves this with a similar approach to Matrix, but as of Oct 2015 there are no open source implementations.) - History synchronisation is very much a second class citizen feature +- Bridging to other protocols and defragmenting existing communication + apps and networks is very much a second class citizen feature - Stanzas aren't framed or reliably delivered without extensions. (See [wiki.xmpp.org](http://wiki.xmpp.org/web/Myths#Myth_Four:_XMPP_is_unreliable_without_a_bunch_of_extensions.) for an XMPP take on this) From 22a2c02d20c0a5ad5a3349500099c8e89771416b Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 18 Apr 2016 10:58:09 +0100 Subject: [PATCH 07/17] Added .NET SDK :) --- .../projects/2016-04-18-matrix-dotnet-sdk.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 supporting-docs/projects/2016-04-18-matrix-dotnet-sdk.md diff --git a/supporting-docs/projects/2016-04-18-matrix-dotnet-sdk.md b/supporting-docs/projects/2016-04-18-matrix-dotnet-sdk.md new file mode 100644 index 00000000..e99137ce --- /dev/null +++ b/supporting-docs/projects/2016-04-18-matrix-dotnet-sdk.md @@ -0,0 +1,10 @@ +--- +layout: project +title: Matrix .NET SDK +categories: projects sdk +author: Half-Shot +maturity: Alpha +--- +# {{ page.title }} + +The .NET SDK provides a object oritented library to interact with Matrix. It is currently mature enough to be used for simple clients and bots. From b020db779e9010cc278d93635f40964fad737bf9 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 18 Apr 2016 11:01:53 +0100 Subject: [PATCH 08/17] Added github link to .NET SDK --- supporting-docs/projects/2016-04-18-matrix-dotnet-sdk.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/supporting-docs/projects/2016-04-18-matrix-dotnet-sdk.md b/supporting-docs/projects/2016-04-18-matrix-dotnet-sdk.md index e99137ce..67ed0c58 100644 --- a/supporting-docs/projects/2016-04-18-matrix-dotnet-sdk.md +++ b/supporting-docs/projects/2016-04-18-matrix-dotnet-sdk.md @@ -8,3 +8,5 @@ maturity: Alpha # {{ page.title }} The .NET SDK provides a object oritented library to interact with Matrix. It is currently mature enough to be used for simple clients and bots. + +[Github](https://github.com/Half-Shot/matrix-dotnet-sdk) From 231d824cfd5dd720c7a496bf0563222150027536 Mon Sep 17 00:00:00 2001 From: Oddvar Lovaas Date: Tue, 19 Apr 2016 14:49:00 +0100 Subject: [PATCH 09/17] change date to move --- ...04-18-matrix-dotnet-sdk.md => 2016-02-07-matrix-dotnet-sdk.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename supporting-docs/projects/{2016-04-18-matrix-dotnet-sdk.md => 2016-02-07-matrix-dotnet-sdk.md} (100%) diff --git a/supporting-docs/projects/2016-04-18-matrix-dotnet-sdk.md b/supporting-docs/projects/2016-02-07-matrix-dotnet-sdk.md similarity index 100% rename from supporting-docs/projects/2016-04-18-matrix-dotnet-sdk.md rename to supporting-docs/projects/2016-02-07-matrix-dotnet-sdk.md From b2028616c12dc03f82557c239c48e6c5e8bc65cf Mon Sep 17 00:00:00 2001 From: Oddvar Lovaas Date: Tue, 19 Apr 2016 14:53:15 +0100 Subject: [PATCH 10/17] spelling --- supporting-docs/projects/2016-02-07-matrix-dotnet-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/supporting-docs/projects/2016-02-07-matrix-dotnet-sdk.md b/supporting-docs/projects/2016-02-07-matrix-dotnet-sdk.md index 67ed0c58..5ea27290 100644 --- a/supporting-docs/projects/2016-02-07-matrix-dotnet-sdk.md +++ b/supporting-docs/projects/2016-02-07-matrix-dotnet-sdk.md @@ -7,6 +7,6 @@ maturity: Alpha --- # {{ page.title }} -The .NET SDK provides a object oritented library to interact with Matrix. It is currently mature enough to be used for simple clients and bots. +The .NET SDK provides an object oriented library to interact with Matrix. It is currently mature enough to be used for simple clients and bots. [Github](https://github.com/Half-Shot/matrix-dotnet-sdk) From 29f675e3c65033e98d73014ab3f80d941914db47 Mon Sep 17 00:00:00 2001 From: "Paul \"LeoNerd\" Evans" Date: Tue, 19 Apr 2016 16:13:17 +0100 Subject: [PATCH 11/17] 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 12/17] 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 13/17] 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 14/17] 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 15/17] 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 16/17] 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 17/17] 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...