From f6da7098574f1fcf0ea73d4ad976a98fcc85783b Mon Sep 17 00:00:00 2001
From: Jonas Platte <jplatte@element.io>
Date: Tue, 29 Mar 2022 23:04:39 +0200
Subject: [PATCH] Mark `from` parameter as optional for `/messages` (#1002)

As per MSC3567, the `from` parameter is now optional for the `/messages` endpoint to allow fetching first or latest room content without having to rely on `/sync`

https://github.com/matrix-org/matrix-doc/pull/3567
---
 .../client_server/newsfragments/1002.feature  |  1 +
 .../api/client-server/message_pagination.yaml | 44 ++++++++++++-------
 2 files changed, 28 insertions(+), 17 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1002.feature

diff --git a/changelogs/client_server/newsfragments/1002.feature b/changelogs/client_server/newsfragments/1002.feature
new file mode 100644
index 000000000..fed2d59b0
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1002.feature
@@ -0,0 +1 @@
+Make `from` optional on `GET /_matrix/client/v3/messages` to allow requesting events from the start or end of the room history, as per [MSC3567](https://github.com/matrix-org/matrix-doc/pull/3567).
diff --git a/data/api/client-server/message_pagination.yaml b/data/api/client-server/message_pagination.yaml
index b63f9e176..cc4d72b41 100644
--- a/data/api/client-server/message_pagination.yaml
+++ b/data/api/client-server/message_pagination.yaml
@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-swagger: '2.0'
+swagger: "2.0"
 info:
   title: "Matrix Client-Server Rooms API"
   version: "1.0.0"
@@ -49,6 +49,10 @@ paths:
         - in: query
           type: string
           name: from
+          x-changedInMatrixVersion:
+            1.3: |
+              Previously, this field was required and paginating from the first or
+              last visible event in the room history wasn't supported.
           description: |-
             The token to start returning events from. This token can be obtained
             from a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,
@@ -57,7 +61,11 @@ paths:
             This endpoint can also accept a value returned as a `start` token
             by a previous request to this endpoint, though servers are not
             required to support this. Clients should not rely on the behaviour.
-          required: true
+
+            If it is not provided, the homeserver shall return a list of messages
+            from the first or last (per the value of the `dir` parameter) visible
+            event in the room history for the requesting user.
+          required: false
           x-example: "s345_678_333"
         - in: query
           type: string
@@ -141,23 +149,25 @@ paths:
                   $ref: "definitions/client_event.yaml"
             required: [start, chunk]
           examples:
-            application/json: {
+            application/json:
+              {
                 "start": "t47429-4392820_219380_26003_2265",
                 "end": "t47409-4357353_219380_26003_2265",
-                "chunk": [
-                  {
-                    "room_id": "!636q39766251:example.com",
-                    "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
-                  },
-                  {
-                    "room_id": "!636q39766251:example.com",
-                    "$ref": "../../event-schemas/examples/m.room.name.yaml"
-                  },
-                  {
-                    "room_id": "!636q39766251:example.com",
-                    "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
-                  }
-                ]
+                "chunk":
+                  [
+                    {
+                      "room_id": "!636q39766251:example.com",
+                      "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
+                    },
+                    {
+                      "room_id": "!636q39766251:example.com",
+                      "$ref": "../../event-schemas/examples/m.room.name.yaml",
+                    },
+                    {
+                      "room_id": "!636q39766251:example.com",
+                      "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml",
+                    },
+                  ],
               }
         403:
           description: >