Merge remote-tracking branch 'matrix-org/master' into travis/s2s/backfill

api/client-server/definitions/public_rooms_response.yaml

@@ -0,0 +1,105 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+
+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: number
+          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: number
+    description: |-
+        An estimate on the total number of public rooms, if the
+        server has an estimate.
+example: {
+  "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
+}

api/client-server/list_public_rooms.yaml

@@ -144,98 +144,7 @@ paths:
         200:
           description: A list of the rooms on the server.
           schema:
-            type: object
+            $ref: "definitions/public_rooms_response.yaml"
-            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: number
-                      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: number
-                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
-              }
       tags:
         - Room discovery
     post:

api/server-server/directory.yaml

@@ -1,69 +0,0 @@
-# Copyright 2017 Kamax.io
-# Copyright 2018 New Vector Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# 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'
-info:
-  title: "Matrix Federation Query API"
-  version: "1.0.0"
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v1
-produces:
-  - application/json
-paths:
-  "/query/directory":
-    get:
-      summary: Retrieve the room ID and list of resident homeservers for a room
-        alias.
-      description: Retrieve the room ID and list of resident homeservers for a room
-        alias.
-      parameters:
-        - in: query
-          name: room_alias
-          type: string
-          description: Room alias.
-          required: true
-          x-example: "#room_alias:example.org"
-      responses:
-        200:
-          description: The corresponding room ID and list of known resident
-            homeservers for the room.
-          schema:
-            type: object
-            properties:
-              room_id:
-                type: string
-                description: The room ID mapped to the queried room alias.
-                x-example: "!roomid1234:example.org"
-              servers:
-                type: array
-                description: An array of server names that are likely to hold
-                  then given room. This list may or may not include the server
-                  answering the query.
-                items:
-                  type: string
-            required:
-              - "room_id"
-              - "servers"
-          examples:
-            application/json: {
-              "room_id": "!roomid1234:example.org",
-              "servers": [
-                "example.org",
-                "example.com",
-                "another.example.com:8449",
-              ]
-            }

api/server-server/event_auth.yaml

@@ -0,0 +1,174 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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'
+info:
+  title: "Matrix Federation Event Authorization API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+consumes: 
+  - application/json
+produces:
+  - application/json
+paths:
+  "/event_auth/{roomId}/{eventId}":
+    get:
+      summary: Get the auth chain for a given event
+      description: |-
+        Retrieves the complete auth chain for a given event.
+      operationId: getEventAuth
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID to get the auth chain for.
+          required: true
+          x-example: "!abc123:matrix.org"
+        - in: path
+          name: eventId
+          type: string
+          description: The event ID to get the auth chain of.
+          required: true
+          x-example: "$helloworld:domain.com"
+      responses:
+        200:
+          description: The auth chain for the event.
+          schema:
+            type: object
+            properties:
+              auth_chain:
+                type: array
+                description: |-
+                  The full set of authorization events that make up the state of
+                  the room, and their authorization events, recursively. 
+                items:
+                  $ref: "definitions/pdu.yaml"
+                example: [{"$ref": "examples/pdu.json"}]
+            required: ['auth_chain']
+  "/query_auth/{roomId}/{eventId}":
+    post:
+      summary: Compare auth chains with the receiving server
+      description: |-
+        Compares the auth chain provided with what the receiving server has for the
+        room ID and event ID combination.
+
+        The auth difference can be calculated in two parts, where the "remote auth"
+        is the auth chain provided by the sending server and the "local auth" is the
+        auth chain the receiving server has. With those lists, the algorithm works
+        bottom-up after sorting each chain by depth then by event ID. The differences
+        are then discovered and returned as the response to this API call.
+      operationId: compareEventAuth
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID to compare the auth chain in.
+          required: true
+          x-example: "!abc123:matrix.org"
+        - in: path
+          name: eventId
+          type: string
+          description: The event ID to compare the auth chain of.
+          required: true
+          x-example: "$helloworld:domain.com"
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              auth_chain:
+                type: array
+                description: The auth chain (the "remote auth").
+                items:
+                  $ref: "definitions/pdu.yaml"
+                example: [{"$ref": "examples/pdu.json"}]
+              missing:
+                type: array
+                description: |-
+                  A list of event IDs that the sender thinks the receiver is missing.
+                items:
+                  type: string
+                example: []
+              rejects:
+                type: object
+                description: |-
+                  The set of events that the sending server has rejected from the provided
+                  auth chain.
+
+                  The ``string`` key is the event ID that was rejected.
+                additionalProperties:
+                  type: object
+                  title: Rejection Reason
+                  properties:
+                    reason:
+                      type: enum
+                      enum: ['auth_error', 'replaced', 'not_ancestor']
+                      description: |-
+                        The reason for the event being rejected.
+                  required: ['reason']
+                example: {
+                  "$some_event:domain.com": {
+                    "reason": "auth_error"
+                  }
+                }
+            required: ['auth_chain']
+      responses:
+        200:
+          description: The auth chain differences, as determined by the receiver.
+          schema:
+            type: object
+            properties:
+              auth_chain:
+                type: array
+                description: |-
+                  The auth chain the receiver has, and used to determine the auth
+                  chain differences (the "local auth").
+                items:
+                  $ref: "definitions/pdu.yaml"
+                example: [{"$ref": "examples/pdu.json"}]
+              missing:
+                type: array
+                description: |-
+                  The list of event IDs that the receiver believes it is missing, 
+                  after comparing the "remote auth" and "local auth" chains.
+                items:
+                  type: string
+                example: ["$a_missing_event:domain.com"]
+              rejects:
+                type: object
+                description: |-
+                  The set of events that the receiving server has rejected from the
+                  auth chain, not including events that the sending server is missing
+                  as determined from the difference algorithm.
+
+                  The ``string`` key is the event ID that was rejected.
+                additionalProperties:
+                  type: object
+                  title: Rejection Reason
+                  properties:
+                    reason:
+                      type: enum
+                      enum: ['auth_error', 'replaced', 'not_ancestor']
+                      description: |-
+                        The reason for the event being rejected.
+                  required: ['reason']
+                example: {
+                  "$some_event:domain.com": {
+                    "reason": "auth_error"
+                  }
+                }
+            required: ['auth_chain', 'missing', 'rejects']

api/server-server/joins.yaml

@@ -20,6 +20,8 @@ host: localhost:8448
 schemes:
   - https
 basePath: /_matrix/federation/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:

api/server-server/keys_query.yaml

@@ -20,6 +20,8 @@ host: localhost:8448
 schemes:
   - https
 basePath: /_matrix/key/v2
+consumes:
+  - application/json
 produces:
   - application/json
 paths:

api/server-server/leaving.yaml

@@ -20,6 +20,8 @@ host: localhost:8448
 schemes:
   - https
 basePath: /_matrix/federation/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:

api/server-server/public_rooms.yaml

@@ -0,0 +1,52 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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'
+info:
+  title: "Matrix Federation Public Rooms API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/publicRooms":
+    get:
+      summary: Get all the public rooms for a homeserver
+      description: |-
+        Gets all the public rooms for the homeserver. This should not return
+        rooms that are listed on another homeserver's directory, just those
+        listed on the receiving homeserver's directory.
+      operationId: getPublicRooms
+      parameters:
+        - in: query
+          name: limit
+          type: integer
+          description: |-
+            The maximum number of rooms to return. Defaults to 0 (no limit).
+          x-example: 10
+        - in: query
+          name: since
+          type: string
+          description: |-
+            A pagination token from a previous call to this endpoint to fetch more
+            rooms.
+          x-example: "GetMoreRoomsTokenHere"
+      responses:
+        200:
+          description: The public room list for the homeserver.
+          schema:
+            $ref: "../client-server/definitions/public_rooms_response.yaml"

api/server-server/query.yaml

@@ -0,0 +1,166 @@
+# Copyright 2017 Kamax.io
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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'
+info:
+  title: "Matrix Federation Query API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/query/{queryType}":
+    get:
+      summary: Query for information
+      description: |-
+        Performs a single query request on the receiving homeserver. The query string
+        arguments are dependent on which type of query is being made. Known query types
+        are specified as their own endpoints as an extension to this definition.
+      operationId: queryInfo
+      parameters:
+        - in: path
+          name: queryType
+          type: string
+          description: The type of query to make
+          required: true
+          x-example: profile
+      responses:
+        200:
+          description: |-
+            The query response. The schema varies depending on the query being made.
+  "/query/directory":
+    get:
+      summary: Query for the room ID and resident homeservers for a room alias
+      description: |-
+        Performs a query to get the mapped room ID and list of resident homeservers in
+        the room for a given room alias. Homeservers should only query room aliases
+        that belong to the target server (identified by the DNS Name in the alias).
+
+        Servers may wish to cache the response to this query to avoid requesting the
+        information too often.
+      operationId: queryRoomDirectory
+      parameters:
+        - in: query
+          name: room_alias
+          type: string
+          description: The room alias to query.
+          required: true
+          x-example: "#room_alias:example.org"
+      responses:
+        200:
+          description: |-
+            The corresponding room ID and list of known resident homeservers for the room.
+          schema:
+            type: object
+            properties:
+              room_id:
+                type: string
+                description: The room ID mapped to the queried room alias.
+                x-example: "!roomid1234:example.org"
+              servers:
+                type: array
+                description: |-
+                  An array of server names that are likely to hold the given room. This 
+                  list may or may not include the server answering the query.
+                items:
+                  type: string
+            required:
+              - "room_id"
+              - "servers"
+          examples:
+            application/json: {
+              "room_id": "!roomid1234:example.org",
+              "servers": [
+                "example.org",
+                "example.com",
+                "another.example.com:8449",
+              ]
+            }
+        404:
+          description: The room alias was not found.
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND",
+              "error": "Room alias not found."
+            }
+  "/query/profile":
+    get:
+      summary: Query for profile information about a given user
+      description: |-
+        Performs a query to get profile information, such as a display name or avatar,
+        for a given user. Homeservers should only query profiles for users that belong
+        to the target server (identified by the DNS Name in the user ID).
+
+        Servers may wish to cache the response to this query to avoid requesting the
+        information too often.
+      parameters:
+        - in: query
+          name: user_id
+          type: string
+          description: The user ID to query.
+          required: true
+          x-example: "@someone:example.org"
+        - in: query
+          name: field
+          type: enum
+          enum: ['displayname', 'avatar_url']
+          description: |-
+            The field to query. If specified, the server will only return the given field
+            in the response. If not specified, the server will return the full profile for
+            the user.
+      responses:
+        200:
+          description: |-
+            The profile for the user. If a ``field`` is specified in the request, only the
+            matching field should be included in the response. If no ``field`` was specified,
+            the response should include the fields of the user's profile that can be made 
+            public, such as the display name and avatar.
+
+            If the user does not have a particular field set on their profile, the server
+            should exclude it from the response body or give it the value ``null``.
+          schema:
+            type: object
+            properties:
+              displayname:
+                type: string
+                description: |-
+                  The display name of the user. May be omitted if the user does not have a
+                  display name set.
+                x-example: "John Doe"
+              avatar_url:
+                type: string
+                description: |-
+                  The avatar URL for the user's avatar. May be omitted if the user does not
+                  have an avatar set.
+                x-example: "mxc://matrix.org/MyC00lAvatar"
+          examples:
+            application/json: {
+              "displayname": "John Doe",
+              "avatar_url": "mxc://matrix.org/MyC00lAvatar"
+            }
+        404:
+          description: The user does not exist or does not have a profile.
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND",
+              "error": "User does not exist."
+            }

api/server-server/query_general.yaml

@@ -1,44 +0,0 @@
-# Copyright 2018 New Vector Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# 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'
-info:
-  title: "Matrix Federation Query API"
-  version: "1.0.0"
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v1
-produces:
-  - application/json
-paths:
-  "/query/{queryType}":
-    get:
-      summary: Query for information
-      description: |-
-        Performs a single query request on the receiving homeserver. The query string
-        arguments are dependent on which type of query is being made. Known query types
-        are specified as their own endpoints as an extension to this definition.
-      operationId: queryInfo
-      parameters:
-        - in: path
-          name: queryType
-          type: string
-          description: The type of query to make
-          required: true
-          x-example: profile
-      responses:
-        200:
-          description: |-
-            The query response. The schema varies depending on the query being made.

api/server-server/third_party_invite.yaml

@@ -20,6 +20,8 @@ host: localhost:8448
 schemes:
   - https
 basePath: /_matrix/federation/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:

api/server-server/transactions.yaml

@@ -20,6 +20,8 @@ host: localhost:8448
 schemes:
   - https
 basePath: /_matrix/federation/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:

specification/appendices/identifier_grammar.rst

@@ -25,8 +25,7 @@ number of identifiers, as described below.
 The server name represents the address at which the homeserver in question can
 be reached by other homeservers. The complete grammar is::
 
-    server_name = dns_name [ ":" port]
+    server_name = host [ ":" port]
-    dns_name = host
     port = *DIGIT
 
 where ``host`` is as defined by `RFC3986, section 3.2.2

specification/modules/tags.rst

@@ -41,7 +41,7 @@ after the rooms with that tag that have an ``order`` key.
 
 The name of a tag MUST not exceed 255 bytes.
 
-Tags namespaces are defined in the following way, depending on how the client are expected to interpret them:
+The tag namespace is defined as follows:
 
 * The namespace ``m.*`` is reserved for tags defined in the Matrix specification. Clients must ignore
   any tags in this namespace they don't understand.

specification/server_server_api.rst

@@ -78,26 +78,34 @@ Server Discovery
 Resolving Server Names
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Each matrix homeserver is identified by a server name consisting of a DNS name
+Each matrix homeserver is identified by a server name consisting of a hostname
 and an optional TLS port.
 
 .. code::
 
-    server_name = dns_name [ ":" tls_port]
+    server_name = hostname [ ":" tls_port]
-    dns_name = <host, see [RFC 3986], Section 3.2.2>
     tls_port = *DIGIT
 
 .. **
 
 If the port is present then the server is discovered by looking up an AAAA or
-A record for the DNS name and connecting to the specified TLS port. If the port
+A record for the hostname and connecting to the specified TLS port. If the port
 is absent then the server is discovered by looking up a ``_matrix._tcp`` SRV
-record for the DNS name. If this record does not exist then the server is
+record for the hostname. If this record does not exist then the server is
-discovered by looking up an AAAA or A record on the DNS name and taking the
+discovered by looking up an AAAA or A record on the hostname and taking the
 default fallback port number of 8448.
 Homeservers may use SRV records to load balance requests between multiple TLS
 endpoints or to failover to another endpoint if an endpoint fails.
 
+If the DNS name is a literal IP address, the port specified or the fallback
+port should be used.
+
+When making requests to servers, use the DNS name of the target server in the
+``Host`` header, regardless of the host given in the SRV record. For example,
+if making a request to ``example.org``, and the SRV record resolves to ``matrix.
+example.org``, the ``Host`` header in the request should be ``example.org``. The
+port number for target server should not appear in the ``Host`` header.
+
 Server implementation
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -440,6 +448,15 @@ The rules are as follows:
 
   I think there is some magic about 3pid invites too.
 
+Retrieving event authorization information
+++++++++++++++++++++++++++++++++++++++++++
+
+The homeserver may be missing event authorization information, or wish to check
+with other servers to ensure it is receiving the correct auth chain. These APIs
+give the homeserver an avenue for getting the information it needs.
+
+{{event_auth_ss_http_api}}
+
 EDUs
 ----
 
@@ -569,8 +586,6 @@ All these URLs are name-spaced within a prefix of::
 
   /_matrix/federation/v1/...
 
-{{query_general_ss_http_api}}
-
 Joining Rooms
 -------------
 
@@ -685,7 +700,7 @@ the events it is missing.
 
 {{backfill_ss_http_api}}
 
-Retriving events
+Retrieving events
 ----------------
 
 In some circumstances, a homeserver may be missing a particular event or information
@@ -882,6 +897,16 @@ A homeserver may provide a TLS client certificate and the receiving homeserver
 may check that the client certificate matches the certificate of the origin
 homeserver.
 
+Public Room Directory
+---------------------
+
+To compliment the `Client-Server API`_'s room directory, homeservers need a
+way to query the public rooms for another server. This can be done by making
+a request to the ``/publicRooms`` endpoint for the server the room directory
+should be retrieved for.
+
+{{public_rooms_ss_http_api}}
+
 
 Presence
 --------
@@ -946,36 +971,18 @@ Rejecting a presence invite::
   - Explain the zero-byte presence inference logic
   See also: docs/client-server/model/presence
 
-Profiles
+Querying for information
---------
+------------------------
-
-The server API for profiles is based entirely on the following Federation
-Queries. There are no additional EDU or PDU types involved, other than the
-implicit ``m.presence`` and ``m.room.member`` events (see section below).
-
-Querying profile information::
-
-  Query type: profile
-
-  Arguments:
-    user_id: the ID of the user whose profile to return
-    field: (optional) string giving a field name
-
-  Returns: JSON object containing the following keys:
-    displayname: string of free-form text
-    avatar_url: string containing an HTTP-scheme URL
-
-If the query contains the optional ``field`` key, it should give the name of a
-result field. If such is present, then the result should contain only a field
-of that name, with no others present. If not, the result should contain as much
-of the user's profile as the homeserver has available and can make public.
 
-Directory
+Queries are a way to retrieve information from a homeserver about a resource,
----------
+such as a user or room. The endpoints here are often called in conjunction with
+a request from a client on the client-server API in order to complete the call.
 
-The server API for directory queries is also based on Federation Queries.
+There are several types of queries that can be made. The generic endpoint to
+represent all queries is described first, followed by the more specific queries
+that can be made.
 
-{{directory_ss_http_api}}
+{{query_ss_http_api}}
 
 Send-to-device messaging
 ------------------------