Merge pull request #2305 from matrix-org/travis/spec/ss-search

Add s2s POST /publicRooms per MSC2197

api/server-server/public_rooms.yaml

@@ -68,3 +68,163 @@ paths:
           description: The public room list for the homeserver.
           schema:
             $ref: "../client-server/definitions/public_rooms_response.yaml"
+    post:
+      summary: Gets the public rooms on the server with optional filter.
+      description: |-
+        Lists the public rooms on the server, with optional filter.
+
+        This API returns paginated responses. The rooms are ordered by the number
+        of joined members, with the largest rooms first.
+
+        Note that this endpoint receives and returns the same format that is seen
+        in the Client-Server API's ``POST /publicRooms`` endpoint.
+      operationId: queryPublicRooms
+      security:
+        - signedRequest: []
+      parameters:
+        - in: body
+          name: body
+          required: true
+          description: |-
+            Options for which rooms to return.
+          schema:
+            type: object
+            properties:
+              limit:
+                type: integer
+                description: |-
+                  Limit the number of results returned.
+              since:
+                type: string
+                description: |-
+                  A pagination token from a previous request, allowing servers
+                  to get the next (or previous) batch of rooms.  The direction
+                  of pagination is specified solely by which token is supplied,
+                  rather than via an explicit flag.
+              filter:
+                type: object
+                title: "Filter"
+                description: |-
+                  Filter to apply to the results.
+                properties:
+                    generic_search_term:
+                      type: string
+                      description: |-
+                        A string to search for in the room metadata, e.g. name,
+                        topic, canonical alias etc. (Optional).
+              include_all_networks:
+                type: boolean
+                description: |-
+                  Whether or not to include all known networks/protocols from
+                  application services on the homeserver. Defaults to false.
+                example: false
+              third_party_instance_id:
+                type: string
+                description: |-
+                  The specific third party network/protocol to request from the
+                  homeserver. Can only be used if ``include_all_networks`` is false.
+                example: "irc"
+            example: {
+              "limit": 10,
+              "filter": {
+                "generic_search_term": "foo"
+              },
+              "include_all_networks": false,
+              "third_party_instance_id": "irc"
+            }
+      responses:
+        200:
+          description: A list of the rooms on the server.
+          schema:
+            type: object
+            description: A list of the rooms on the server.
+            required: ["chunk"]
+            properties:
+              chunk:
+                title: "PublicRoomsChunks"
+                type: array
+                description: |-
+                  A paginated chunk of public rooms.
+                items:
+                  type: object
+                  title: "PublicRoomsChunk"
+                  required:
+                    - room_id
+                    - num_joined_members
+                    - world_readable
+                    - guest_can_join
+                  properties:
+                    aliases:
+                      type: array
+                      description: |-
+                        Aliases of the room. May be empty.
+                      items:
+                        type: string
+                    canonical_alias:
+                      type: string
+                      description: |-
+                        The canonical alias of the room, if any.
+                    name:
+                      type: string
+                      description: |-
+                        The name of the room, if any.
+                    num_joined_members:
+                      type: integer
+                      description: |-
+                        The number of members joined to the room.
+                    room_id:
+                      type: string
+                      description: |-
+                        The ID of the room.
+                    topic:
+                      type: string
+                      description: |-
+                        The topic of the room, if any.
+                    world_readable:
+                      type: boolean
+                      description: |-
+                        Whether the room may be viewed by guest users without joining.
+                    guest_can_join:
+                      type: boolean
+                      description: |-
+                        Whether guest users may join the room and participate in it.
+                        If they can, they will be subject to ordinary power level
+                        rules like any other user.
+                    avatar_url:
+                      type: string
+                      description: The URL for the room's avatar, if one is set.
+              next_batch:
+                type: string
+                description: |-
+                  A pagination token for the response. The absence of this token
+                  means there are no more results to fetch and the client should
+                  stop paginating.
+              prev_batch:
+                type: string
+                description: |-
+                  A pagination token that allows fetching previous results. The
+                  absence of this token means there are no results before this
+                  batch, i.e. this is the first batch.
+              total_room_count_estimate:
+                type: integer
+                description: |-
+                   An estimate on the total number of public rooms, if the
+                   server has an estimate.
+          examples:
+            application/json: {
+              "chunk": [
+                {
+                  "aliases": ["#murrays:cheese.bar"],
+                  "avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
+                  "guest_can_join": false,
+                  "name": "CHEESE",
+                  "num_joined_members": 37,
+                  "room_id": "!ol19s:bleecker.street",
+                  "topic": "Tasty tasty cheese",
+                  "world_readable": true
+                }
+              ],
+              "next_batch": "p190q",
+              "prev_batch": "p1902",
+              "total_room_count_estimate": 115
+            }

changelogs/server_server/newsfragments/2035.new

@@ -0,0 +1 @@
+Add new ``POST /publicRooms`` endpoint for filtering the room directory.