Merge pull request #1554 from turt2live/travis/general/appservice-directories

Application service room directories (and other third party network things)

api/application-service/application_service.yaml

@@ -96,243 +96,3 @@ paths:
             }
           schema:
             type: object
-  "/_matrix/app/unstable/thirdparty/protocol/{protocol}":
-    get:
-      summary: Retrieve metadata about a specific protocol that the application service supports.
-      description: |-
-        This API is called by the homeserver when it wants to present clients
-        with specific information about the various third party networks that
-        an application service supports.
-      operationId: getProtocolMetadata
-      parameters:
-        - in: path
-          name: protocol
-          type: string
-          description: The protocol ID.
-          required: true
-          x-example: "irc"
-      responses:
-        200:
-          description: The protocol was found and metadata returned.
-          schema:
-            $ref: definitions/protocol_metadata.yaml
-        401:
-          description: |-
-            The homeserver has not supplied credentials to the application service.
-            Optional error information can be included in the body of this response.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-        403:
-          description: |-
-            The credentials supplied by the homeserver were rejected.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-        404:
-          description: No protocol was found with the given path.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-  "/_matrix/app/unstable/thirdparty/user/{protocol}":
-    get:
-      summary: Retrieve the Matrix User ID of a corresponding third party user.
-      description: |-
-        This API is called by the homeserver in order to retrieve a Matrix
-        User ID linked to a user on the third party network, given a set of
-        user parameters.
-      operationId: queryUserByProtocol
-      parameters:
-        - in: path
-          name: protocol
-          type: string
-          description: The protocol ID.
-          required: true
-          x-example: irc
-        - in: query
-          name: fields...
-          type: string
-          description: |-
-            One or more custom fields that are passed to the application
-            service to help identify the user.
-      responses:
-        200:
-          description: The Matrix User IDs found with the given parameters.
-          schema:
-            $ref: definitions/user_batch.yaml
-        401:
-          description: |-
-            The homeserver has not supplied credentials to the application service.
-            Optional error information can be included in the body of this response.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-        403:
-          description: |-
-            The credentials supplied by the homeserver were rejected.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-        404:
-          description: No users were found with the given parameters.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-  "/_matrix/app/unstable/thirdparty/location/{protocol}":
-    get:
-      summary: Retreive Matrix-side portal rooms leading to a third party location.
-      description: |-
-        Retrieve a list of Matrix portal rooms that lead to the matched third party location.
-      operationId: queryLocationByProtocol
-      parameters:
-        - in: path
-          name: protocol
-          type: string
-          description: The protocol ID.
-          required: true
-          x-example: irc
-        - in: query
-          name: fields...
-          type: string
-          description: |-
-            One or more custom fields that are passed to the application
-            service to help identify the third party location.
-      responses:
-        200:
-          description: At least one portal room was found.
-          schema:
-            $ref: definitions/location_batch.yaml
-        401:
-          description: |-
-            The homeserver has not supplied credentials to the application service.
-            Optional error information can be included in the body of this response.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-        403:
-          description: |-
-            The credentials supplied by the homeserver were rejected.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-        404:
-          description: No mappings were found with the given parameters.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-  "/_matrix/app/unstable/thirdparty/location":
-    get:
-      summary: Reverse-lookup third party locations given a Matrix room alias.
-      description: |-
-        Retreive an array of third party network locations from a Matrix room
-        alias.
-      operationId: queryLocationByAlias
-      parameters:
-        - in: query
-          name: alias
-          type: string
-          description: The Matrix room alias to look up.
-      responses:
-        200:
-          description: |-
-            All found third party locations.
-          schema:
-            $ref: definitions/location_batch.yaml
-        401:
-          description: |-
-            The homeserver has not supplied credentials to the application service.
-            Optional error information can be included in the body of this response.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-        403:
-          description: |-
-            The credentials supplied by the homeserver were rejected.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-        404:
-          description: No mappings were found with the given parameters.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-  "/_matrix/app/unstable/thirdparty/user":
-    get:
-      summary: Reverse-lookup third party users given a Matrix User ID.
-      description: |-
-        Retreive an array of third party users from a Matrix User ID.
-      operationId: queryUserByID
-      parameters:
-        - in: query 
-          name: userid
-          type: string
-          description: The Matrix User ID to look up.
-      responses:
-        200:
-          description: |-
-            An array of third party users.
-          schema:
-            $ref: definitions/user_batch.yaml
-        401:
-          description: |-
-            The homeserver has not supplied credentials to the application service.
-            Optional error information can be included in the body of this response.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-        403:
-          description: |-
-            The credentials supplied by the homeserver were rejected.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
-        404:
-          description: No mappings were found with the given parameters.
-          examples:
-            application/json: {
-              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
-            }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml

api/application-service/definitions/location.yaml

@@ -19,12 +19,14 @@ properties:
   protocol:
     description: The protocol ID that the third party location is a part of.
     type: string
-    example: irc
+    example: "irc"
   fields:
     description: Information used to identify this third party location.
     type: object
-    example:
+    example: {
-      "network": "freenode"
+      "network": "freenode",
       "channel": "#matrix"
+    }
+required: ['alias', 'protocol', 'fields']
 title: Location
 type: object

api/application-service/definitions/protocol.yaml

@@ -11,41 +11,60 @@
 # 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.
+title: Protocol
+type: object
 properties:
   user_fields:
-    description: Fields used to identify a third party user.
+    description: |-
+      Fields which may be used to identify a third party user. These should be
+      ordered to suggest the way that entities may be grouped, where higher
+      groupings are ordered first. For example, the name of a network should be
+      searched before the nickname of a user.
     type: array
     items:
       type: string
       description: Field used to identify a third party user.
     example: ["network", "nickname"]
   location_fields:
-    description: Fields used to identify a third party location.
+    description: |-
+      Fields which may be used to identify a third party location. These should be
+      ordered to suggest the way that entities may be grouped, where higher
+      groupings are ordered first. For example, the name of a network should be
+      searched before the name of a channel.
     type: array
     items:
       type: string
       description: Field used to identify a third party location.
     example: ["network", "channel"]
   icon:
-    description: An icon representing the third party protocol.
+    description: A content URI representing an icon for the third party protocol.
     type: string
     example: "mxc://example.org/aBcDeFgH"
   field_types:
     title: Field Types
-    description: All location or user fields should have an entry here.
+    description: |-
+      The type definitions for the fields defined in the ``user_fields`` and 
+      ``location_fields``. Each entry in those arrays MUST have an entry here. The
+      ``string`` key for this object is field name itself.
+
+      May be an empty object if no fields are defined.
     type: object
-    properties:
+    additionalProperties:
-      fieldname:
+      title: Field Type
-        title: Field Type
+      description: Definition of valid values for a field.
-        description: Definition of valid values for a field.
+      type: object
-        type: object
+      properties:
-        properties:
+        regexp:
-          regexp:
+          description: |-
-            description: A regular expression for validation of a field's value.
+            A regular expression for validation of a field's value. This may be relatively
-            type: string
+            coarse to verify the value as the application service providing this protocol
-          placeholder:
+            may apply additional validation or filtering.
-            description: An placeholder serving as a valid example of the field value.
+          type: string
-            type: string
+        placeholder:
+          description: An placeholder serving as a valid example of the field value.
+          type: string
+      required: ['regexp', 'placeholder']
+    required: ['fieldname']
     example: {
       "network": {
         "regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
@@ -63,17 +82,32 @@ properties:
   instances:
     description: |-
       A list of objects representing independent instances of configuration.
-      For instance multiple networks on IRC if multiple are bridged by the
+      For example, multiple networks on IRC if multiple are provided by the
-      same bridge.
+      same application service.
     type: array
     items:
       type: object
-      example: {
+      title: Protocol Instance
-        "desc": "Freenode",
+      properties:
-        "icon": "mxc://example.org/JkLmNoPq",
+        desc:
-        "fields": {
+          type: string
-          "network": "freenode.net",
+          description: A human-readable description for the protocol, such as the name.
-        }
+          example: "Freenode"
-      }
+        icon:
-title: Protocol
+          type: string
-type: object
+          description: |-
+            An optional content URI representing the protocol. Overrides the one provided
+            at the higher level Protocol object.
+          example: "mxc://example.org/JkLmNoPq"
+        fields:
+          type: object
+          description: Preset values for ``fields`` the client may use to search by.
+          example: {
+            "network": "freenode"
+          }
+        network_id:
+          type: string
+          description: A unique identifier across all instances.
+          example: "freenode"
+      required: ['desc', 'fields', 'network_id']
+required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']

api/application-service/definitions/protocol_metadata.yaml

@@ -36,6 +36,7 @@ example: {
     },
     "instances": [
       {
+        "network_id": "freenode",
         "desc": "Freenode",
         "icon": "mxc://example.org/JkLmNoPq",
         "fields": {
@@ -59,6 +60,7 @@ example: {
     },
     "instances": [
       {
+        "network_id": "gitter",
         "desc": "Gitter",
         "icon": "mxc://example.org/zXyWvUt",
         "fields": {}

api/application-service/definitions/user.yaml

@@ -21,11 +21,13 @@ properties:
   protocol:
     description: The protocol ID that the third party location is a part of.
     type: string
-    example: gitter
+    example: "gitter"
   fields:
     description: Information used to identify this third party location.
     type: object
-    example:
+    example: {
       "user": "jim"
+    }
+required: ['userid', 'protocol', 'fields']
 title: User
 type: object

api/application-service/protocols.yaml

@@ -0,0 +1,267 @@
+# 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 Application Service API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: "/"
+consumes:
+  - application/json
+produces:
+  - application/json
+paths:
+  "/_matrix/app/unstable/thirdparty/protocol/{protocol}":
+    get:
+      summary: Retrieve metadata about a specific protocol that the application service supports.
+      description: |-
+        This API is called by the homeserver when it wants to present clients
+        with specific information about the various third party networks that
+        an application service supports.
+      operationId: getProtocolMetadata
+      parameters:
+        - in: path
+          name: protocol
+          type: string
+          description: The protocol ID.
+          required: true
+          x-example: "irc"
+      responses:
+        200:
+          description: The protocol was found and metadata returned.
+          schema:
+            $ref: definitions/protocol_metadata.yaml
+        401:
+          description: |-
+            The homeserver has not supplied credentials to the application service.
+            Optional error information can be included in the body of this response.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        403:
+          description: |-
+            The credentials supplied by the homeserver were rejected.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        404:
+          description: No protocol was found with the given path.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+  "/_matrix/app/unstable/thirdparty/user/{protocol}":
+    get:
+      summary: Retrieve the Matrix User ID of a corresponding third party user.
+      description: |-
+        This API is called by the homeserver in order to retrieve a Matrix
+        User ID linked to a user on the third party network, given a set of
+        user parameters.
+      operationId: queryUserByProtocol
+      parameters:
+        - in: path
+          name: protocol
+          type: string
+          description: The protocol ID.
+          required: true
+          x-example: irc
+        - in: query
+          name: fields...
+          type: string
+          description: |-
+            One or more custom fields that are passed to the application
+            service to help identify the user.
+      responses:
+        200:
+          description: The Matrix User IDs found with the given parameters.
+          schema:
+            $ref: definitions/user_batch.yaml
+        401:
+          description: |-
+            The homeserver has not supplied credentials to the application service.
+            Optional error information can be included in the body of this response.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        403:
+          description: |-
+            The credentials supplied by the homeserver were rejected.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        404:
+          description: No users were found with the given parameters.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+  "/_matrix/app/unstable/thirdparty/location/{protocol}":
+    get:
+      summary: Retrieve Matrix-side portal rooms leading to a third party location.
+      description: |-
+        Retrieve a list of Matrix portal rooms that lead to the matched third party location.
+      operationId: queryLocationByProtocol
+      parameters:
+        - in: path
+          name: protocol
+          type: string
+          description: The protocol ID.
+          required: true
+          x-example: irc
+        - in: query
+          name: fields...
+          type: string
+          description: |-
+            One or more custom fields that are passed to the application
+            service to help identify the third party location.
+      responses:
+        200:
+          description: At least one portal room was found.
+          schema:
+            $ref: definitions/location_batch.yaml
+        401:
+          description: |-
+            The homeserver has not supplied credentials to the application service.
+            Optional error information can be included in the body of this response.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        403:
+          description: |-
+            The credentials supplied by the homeserver were rejected.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        404:
+          description: No mappings were found with the given parameters.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+  "/_matrix/app/unstable/thirdparty/location":
+    get:
+      summary: Reverse-lookup third party locations given a Matrix room alias.
+      description: |-
+        Retrieve an array of third party network locations from a Matrix room
+        alias.
+      operationId: queryLocationByAlias
+      parameters:
+        - in: query
+          name: alias
+          type: string
+          description: The Matrix room alias to look up.
+      responses:
+        200:
+          description: |-
+            All found third party locations.
+          schema:
+            $ref: definitions/location_batch.yaml
+        401:
+          description: |-
+            The homeserver has not supplied credentials to the application service.
+            Optional error information can be included in the body of this response.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        403:
+          description: |-
+            The credentials supplied by the homeserver were rejected.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        404:
+          description: No mappings were found with the given parameters.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+  "/_matrix/app/unstable/thirdparty/user":
+    get:
+      summary: Reverse-lookup third party users given a Matrix User ID.
+      description: |-
+        Retrieve an array of third party users from a Matrix User ID.
+      operationId: queryUserByID
+      parameters:
+        - in: query 
+          name: userid
+          type: string
+          description: The Matrix User ID to look up.
+      responses:
+        200:
+          description: |-
+            An array of third party users.
+          schema:
+            $ref: definitions/user_batch.yaml
+        401:
+          description: |-
+            The homeserver has not supplied credentials to the application service.
+            Optional error information can be included in the body of this response.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        403:
+          description: |-
+            The credentials supplied by the homeserver were rejected.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        404:
+          description: No mappings were found with the given parameters.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml

api/client-server/appservice_room_directory.yaml

@@ -0,0 +1,87 @@
+# 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 Client-Server Application Service Room Directory API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  # Note: this is the same access_token definition used elsewhere in the client
+  # server API, however this expects an access token for an application service.
+  $ref: definitions/security.yaml
+paths:
+  "/directory/list/appservice/{networkId}/{roomId}":
+    put:
+      summary: |-
+        Updates a room's visibility in the application service's room directory.
+      description: |-
+        Updates the visibility of a given room on the application service's room
+        directory.
+
+        This API is similar to the room directory visibility API used by clients
+        to update the homeserver's more general room directory.
+
+        This API requires the use of an application service access token (``as_token``)
+        instead of a typical client's access_token. This API cannot be invoked by
+        users who are not identified as application services.
+      operationId: updateAppserviceRoomDirectoryVsibility
+      parameters:
+        - in: path
+          type: string
+          name: networkId
+          description: |-
+            The protocol (network) ID to update the room list for. This would
+            have been provided by the application service as being listed as
+            a supported protocol.
+          required: true
+          x-example: "irc"
+        - in: path
+          type: string
+          name: roomId
+          description: The room ID to add to the directory.
+          required: true
+          x-example: "!somewhere:domain.com"
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              visibility:
+                type: enum
+                enum: ["public", "private"]
+                description: |-
+                  Whether the room should be visible (public) in the directory
+                  or not (private).
+                example: "public"
+            required: ['visibility']
+      security:
+        # again, this is the appservice's token - not a typical client's
+        - accessToken: []
+      responses:
+        200:
+          description: The room's directory visibility has been updated.
+          schema:
+            type: object
+          examples:
+            application/json: {}
+      tags:
+        - Application service room directory management

api/client-server/list_public_rooms.yaml

@@ -194,8 +194,26 @@ paths:
                       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"}}
+              "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.

api/client-server/third_party_lookup.yaml

@@ -73,7 +73,7 @@ paths:
             $ref: definitions/errors/error.yaml
   "/thirdparty/location/{protocol}":
     get:
-      summary: Retreive Matrix-side portals rooms leading to a third party location.
+      summary: Retrieve Matrix-side portals rooms leading to a third party location.
       description: |-
         Requesting this endpoint with a valid protocol name results in a list
         of successful mapping results in a JSON array. Each result contains
@@ -151,7 +151,7 @@ paths:
     get:
       summary: Reverse-lookup third party locations given a Matrix room alias.
       description: |-
-        Retreive an array of third party network locations from a Matrix room
+        Retrieve an array of third party network locations from a Matrix room
         alias.
       operationId: queryLocationByAlias
       security:
@@ -181,7 +181,7 @@ paths:
     get:
       summary: Reverse-lookup third party users given a Matrix User ID.
       description: |-
-        Retreive an array of third party users from a Matrix User ID.
+        Retrieve an array of third party users from a Matrix User ID.
       operationId: queryUserByID
       security:
         - accessToken: []

api/server-server/public_rooms.yaml

@@ -49,6 +49,20 @@ paths:
             A pagination token from a previous call to this endpoint to fetch more
             rooms.
           x-example: "GetMoreRoomsTokenHere"
+        - in: query
+          name: include_all_networks
+          type: boolean
+          description: |-
+            Whether or not to include all networks/protocols defined by application
+            services on the homeserver. Defaults to false.
+          x-example: false
+        - in: query
+          name: 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.
+          x-example: "irc"
       responses:
         200:
           description: The public room list for the homeserver.

changelogs/client_server/newsfragments/1554.feature

@@ -0,0 +1 @@
+Add third party network room directories, as provided by application services.

specification/application_service_api.rst

@@ -180,6 +180,27 @@ this request (e.g. to join a room alias).
 {{query_room_as_http_api}}
 
 
+Third party networks
+++++++++++++++++++++
+
+Application services may declare which protocols they support via their registration
+configuration for the homeserver. These networks are generally for third party services
+such as IRC that the application service is managing. Application services may populate
+a Matrix room directory for their registered protocols, as defined in the Client-Server
+API Extensions.
+
+Each protocol may have several "locations" (also known as "third party locations" or "3PLs").
+A location within a protocol is a place in the third party network, such as an IRC channel.
+Users of the third party network may also be represented by the application service.
+
+Locations and users can be searched by fields defined by the application service, such
+as by display name or other attribute. When clients request the homeserver to search
+in a particular "network" (protocol), the search fields will be passed along to the
+application service for filtering.
+
+{{protocols_as_http_api}}
+
+
 HTTP APIs
 +++++++++
 
@@ -198,6 +219,9 @@ Application services can use a more powerful version of the
 client-server API by identifying itself as an application service to the
 homeserver.
 
+Endpoints defined in this section MUST be supported by homeservers in the
+client-server API as accessible only by application services.
+
 Identity assertion
 ++++++++++++++++++
 The client-server API infers the user ID from the ``access_token`` provided in
@@ -294,6 +318,15 @@ API MUST do so with a virtual user (provide a ``user_id`` via the query string).
 is expected that the application service use the transactions pushed to it to
 handle events rather than syncing with the user implied by ``sender_localpart``.
 
+Application service room directories
+++++++++++++++++++++++++++++++++++++
+
+Application services can maintain their own room directories for their defined
+third party protocols. These room directories may be accessed by clients through
+additional parameters on the ``/publicRooms`` client-server endpoint.
+
+{{appservice_room_directory_cs_http_api}}
+
 Event fields
 ~~~~~~~~~~~~