Factor out all the common parameters of the various /relations apis (#1745)

Contributed by @zecakeh bd54781052.

Co-authored-by: Richard van der Hoff <richard@matrix.org>

changelogs/internal/newsfragments/1745.clarification

@@ -0,0 +1 @@
+Factor out all the common parameters of the various `/relations` apis.

data/api/client-server/relations.yaml

@@ -33,69 +33,12 @@ paths:
       security:
         - accessToken: []
       parameters:
-        - in: path
+        - $ref: '#/components/parameters/roomId'
-          name: roomId
+        - $ref: '#/components/parameters/eventId'
-          description: The ID of the room containing the parent event.
+        - $ref: '#/components/parameters/from'
-          required: true
+        - $ref: '#/components/parameters/to'
-          example: "!636q39766251:matrix.org"
+        - $ref: '#/components/parameters/limit'
-          schema:
+        - $ref: '#/components/parameters/dir'
-            type: string
-        - in: path
-          name: eventId
-          description: The ID of the parent event whose child events are to be returned.
-          required: true
-          example: $asfDuShaf7Gafaw
-          schema:
-            type: string
-        - in: query
-          name: from
-          description: |-
-            The pagination token to start returning results from. If not supplied, results
-            start at the most recent topological event known to the server.
-
-            Can be a `next_batch` or `prev_batch` token from a previous call, or a returned
-            `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
-            or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
-          required: false
-          example: page2_token
-          schema:
-            type: string
-        - in: query
-          name: to
-          description: |-
-            The pagination token to stop returning results at. If not supplied, results
-            continue up to `limit` or until there are no more events.
-
-            Like `from`, this can be a previous token from a prior call to this endpoint
-            or from `/messages` or `/sync`.
-          required: false
-          example: page3_token
-          schema:
-            type: string
-        - in: query
-          name: limit
-          description: |-
-            The maximum number of results to return in a single `chunk`. The server can
-            and should apply a maximum value to this parameter to avoid large responses.
-
-            Similarly, the server should apply a default value when not supplied.
-          required: false
-          example: 20
-          schema:
-            type: integer
-        - in: query
-          name: dir
-          x-addedInMatrixVersion: "1.4"
-          description: |-
-            Optional (default `b`) direction to return events from. If this is set to `f`, events
-            will be returned in chronological order starting at `from`. If it
-            is set to `b`, events will be returned in *reverse* chronological
-            order, again starting at `from`.
-          schema:
-            type: string
-            enum:
-              - b
-              - f
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
@@ -107,7 +50,9 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                allOf:
+                  - $ref: '#/components/schemas/response'
+                  - type: object
                     properties:
                       chunk:
                         title: ChildEventsChunk
@@ -115,52 +60,14 @@ paths:
                         description: The child events of the requested event, ordered topologically
                           most-recent first.
                         items:
-                      allOf:
+                          $ref: definitions/client_event.yaml
-                        - $ref: definitions/client_event.yaml
-                  next_batch:
-                    type: string
-                    description: |-
-                      An opaque string representing a pagination token. The absence of this token
-                      means there are no more results to fetch and the client should stop paginating.
-                  prev_batch:
-                    type: string
-                    description: |-
-                      An opaque string representing a pagination token. The absence of this token
-                      means this is the start of the result set, i.e. this is the first batch/page.
                     required:
                       - chunk
               examples:
                 response:
-                  value: {
+                  $ref: '#/components/examples/response'
-                    "chunk": [
-                      {
-                        "room_id": "!636q39766251:matrix.org",
-                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
-                        "content": {
-                          "m.relates_to": {
-                            "rel_type": "org.example.my_relation",
-                            "event_id": "$asfDuShaf7Gafaw"
-                          }
-                        }
-                      }
-                    ],
-                    "next_batch": "page2_token",
-                    "prev_batch": "page1_token"
-                  }
         "404":
-          description: |-
+          $ref: '#/components/responses/404'
-            The parent event was not found or the user does not have permission to read
-            this event (it might be contained in history that is not accessible to the user).
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_NOT_FOUND",
-                    "error": "Event not found."
-                  }
       tags:
         - Event relationships
   # The same as above, with added `/{relType}`
@@ -182,77 +89,13 @@ paths:
       security:
         - accessToken: []
       parameters:
-        - in: path
+        - $ref: '#/components/parameters/roomId'
-          name: roomId
+        - $ref: '#/components/parameters/eventId'
-          description: The ID of the room containing the parent event.
+        - $ref: '#/components/parameters/relType'
-          required: true
+        - $ref: '#/components/parameters/from'
-          example: "!636q39766251:matrix.org"
+        - $ref: '#/components/parameters/to'
-          schema:
+        - $ref: '#/components/parameters/limit'
-            type: string
+        - $ref: '#/components/parameters/dir'
-        - in: path
-          name: eventId
-          description: The ID of the parent event whose child events are to be returned.
-          required: true
-          example: $asfDuShaf7Gafaw
-          schema:
-            type: string
-        - in: path
-          name: relType
-          description: The [relationship type](/client-server-api/#relationship-types) to
-            search for.
-          required: true
-          example: org.example.my_relation
-          schema:
-            type: string
-        - in: query
-          name: from
-          description: |-
-            The pagination token to start returning results from. If not supplied, results
-            start at the most recent topological event known to the server.
-
-            Can be a `next_batch` or `prev_batch` token from a previous call, or a returned
-            `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
-            or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
-          required: false
-          example: page2_token
-          schema:
-            type: string
-        - in: query
-          name: to
-          description: |-
-            The pagination token to stop returning results at. If not supplied, results
-            continue up to `limit` or until there are no more events.
-
-            Like `from`, this can be a previous token from a prior call to this endpoint
-            or from `/messages` or `/sync`.
-          required: false
-          example: page3_token
-          schema:
-            type: string
-        - in: query
-          name: limit
-          description: |-
-            The maximum number of results to return in a single `chunk`. The server can
-            and should apply a maximum value to this parameter to avoid large responses.
-
-            Similarly, the server should apply a default value when not supplied.
-          required: false
-          example: 20
-          schema:
-            type: integer
-        - in: query
-          name: dir
-          x-addedInMatrixVersion: "1.4"
-          description: |-
-            Optional (default `b`) direction to return events from. If this is set to `f`, events
-            will be returned in chronological order starting at `from`. If it
-            is set to `b`, events will be returned in *reverse* chronological
-            order, again starting at `from`.
-          schema:
-            type: string
-            enum:
-              - b
-              - f
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
@@ -264,7 +107,9 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                allOf:
+                  - $ref: '#/components/schemas/response'
+                  - type: object
                     properties:
                       chunk:
                         title: ChildEventsChunk
@@ -274,52 +119,14 @@ paths:
                           most-recent first. The events returned will match the `relType`
                           supplied in the URL.
                         items:
-                      allOf:
+                          $ref: definitions/client_event.yaml
-                        - $ref: definitions/client_event.yaml
-                  next_batch:
-                    type: string
-                    description: |-
-                      An opaque string representing a pagination token. The absence of this token
-                      means there are no more results to fetch and the client should stop paginating.
-                  prev_batch:
-                    type: string
-                    description: |-
-                      An opaque string representing a pagination token. The absence of this token
-                      means this is the start of the result set, i.e. this is the first batch/page.
                     required:
                       - chunk
               examples:
                 response:
-                  value: {
+                  $ref: '#/components/examples/response'
-                    "chunk": [
-                      {
-                        "room_id": "!636q39766251:matrix.org",
-                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
-                        "content": {
-                          "m.relates_to": {
-                            "rel_type": "org.example.my_relation",
-                            "event_id": "$asfDuShaf7Gafaw"
-                          }
-                        }
-                      }
-                    ],
-                    "next_batch": "page2_token",
-                    "prev_batch": "page1_token"
-                  }
         "404":
-          description: |-
+          $ref: '#/components/responses/404'
-            The parent event was not found or the user does not have permission to read
-            this event (it might be contained in history that is not accessible to the user).
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_NOT_FOUND",
-                    "error": "Event not found."
-                  }
       tags:
         - Event relationships
   # The same as above, with added `/{eventType}`
@@ -342,28 +149,9 @@ paths:
       security:
         - accessToken: []
       parameters:
-        - in: path
+        - $ref: '#/components/parameters/roomId'
-          name: roomId
+        - $ref: '#/components/parameters/eventId'
-          description: The ID of the room containing the parent event.
+        - $ref: '#/components/parameters/relType'
-          required: true
-          example: "!636q39766251:matrix.org"
-          schema:
-            type: string
-        - in: path
-          name: eventId
-          description: The ID of the parent event whose child events are to be returned.
-          required: true
-          example: $asfDuShaf7Gafaw
-          schema:
-            type: string
-        - in: path
-          name: relType
-          description: The [relationship type](/client-server-api/#relationship-types) to
-            search for.
-          required: true
-          example: org.example.my_relation
-          schema:
-            type: string
         - in: path
           name: eventType
           description: |-
@@ -375,7 +163,77 @@ paths:
           example: m.room.message
           schema:
             type: string
-        - in: query
+        - $ref: '#/components/parameters/from'
+        - $ref: '#/components/parameters/to'
+        - $ref: '#/components/parameters/limit'
+        - $ref: '#/components/parameters/dir'
+      responses:
+        # note: this endpoint deliberately does not support rate limiting, therefore a
+        # 429 error response is not included.
+        "200":
+          description: |-
+            The paginated child events which point to the parent. If no events are
+            pointing to the parent or the pagination yields no results, an empty `chunk`
+            is returned.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/response'
+                  - type: object
+                    properties:
+                      chunk:
+                        title: ChildEventsChunk
+                        type: array
+                        description: |-
+                          The child events of the requested event, ordered topologically most-recent
+                          first. The events returned will match the `relType` and `eventType` supplied
+                          in the URL.
+                        items:
+                          $ref: definitions/client_event.yaml
+                    required:
+                      - chunk
+              examples:
+                response:
+                  $ref: '#/components/examples/response'
+        "404":
+          $ref: '#/components/responses/404'
+      tags:
+        - Event relationships
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml
+  parameters:
+    roomId:
+      in: path
+      name: roomId
+      description: The ID of the room containing the parent event.
+      required: true
+      example: "!636q39766251:matrix.org"
+      schema:
+        type: string
+    eventId:
+      in: path
+      name: eventId
+      description: The ID of the parent event whose child events are to be returned.
+      required: true
+      example: $asfDuShaf7Gafaw
+      schema:
+        type: string
+    from:
+      in: query
       name: from
       description: |-
         The pagination token to start returning results from. If not supplied, results
@@ -388,7 +246,8 @@ paths:
       example: page2_token
       schema:
         type: string
-        - in: query
+    to:
+      in: query
       name: to
       description: |-
         The pagination token to stop returning results at. If not supplied, results
@@ -400,7 +259,8 @@ paths:
       example: page3_token
       schema:
         type: string
-        - in: query
+    limit:
+      in: query
       name: limit
       description: |-
         The maximum number of results to return in a single `chunk`. The server can
@@ -411,7 +271,8 @@ paths:
       example: 20
       schema:
         type: integer
-        - in: query
+    dir:
+      in: query
       name: dir
       x-addedInMatrixVersion: "1.4"
       description: |-
@@ -424,29 +285,19 @@ paths:
         enum:
           - b
           - f
-      responses:
+    relType:
-        # note: this endpoint deliberately does not support rate limiting, therefore a
+      in: path
-        # 429 error response is not included.
+      name: relType
-        "200":
+      description: The [relationship type](/client-server-api/#relationship-types) to
-          description: |-
+        search for.
-            The paginated child events which point to the parent. If no events are
+      required: true
-            pointing to the parent or the pagination yields no results, an empty `chunk`
+      example: org.example.my_relation
-            is returned.
-          content:
-            application/json:
       schema:
+        type: string
+  schemas:
+    response:
       type: object
       properties:
-                  chunk:
-                    title: ChildEventsChunk
-                    type: array
-                    description: |-
-                      The child events of the requested event, ordered topologically most-recent
-                      first. The events returned will match the `relType` and `eventType` supplied
-                      in the URL.
-                    items:
-                      allOf:
-                        - $ref: definitions/client_event.yaml
         next_batch:
           type: string
           description: |-
@@ -457,8 +308,21 @@ paths:
           description: |-
             An opaque string representing a pagination token. The absence of this token
             means this is the start of the result set, i.e. this is the first batch/page.
-                required:
+  responses:
-                  - chunk
+    "404":
+      description: |-
+        The parent event was not found or the user does not have permission to read
+        this event (it might be contained in history that is not accessible to the user).
+      content:
+        application/json:
+          schema:
+            $ref: definitions/errors/error.yaml
+          examples:
+            response:
+              value: {
+                "errcode": "M_NOT_FOUND",
+                "error": "Event not found."
+              }
   examples:
     response:
       value: {
@@ -477,34 +341,3 @@ paths:
         "next_batch": "page2_token",
         "prev_batch": "page1_token"
       }
-        "404":
-          description: |-
-            The parent event was not found or the user does not have permission to read
-            this event (it might be contained in history that is not accessible to the user).
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_NOT_FOUND",
-                    "error": "Event not found."
-                  }
-      tags:
-        - Event relationships
-servers:
-  - url: "{protocol}://{hostname}{basePath}"
-    variables:
-      protocol:
-        enum:
-          - http
-          - https
-        default: https
-      hostname:
-        default: localhost:8008
-      basePath:
-        default: /_matrix/client/v1
-components:
-  securitySchemes:
-    $ref: definitions/security.yaml