Document third party network/protocol directories (for appservices)

Fixes https://github.com/matrix-org/matrix-doc/issues/869

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/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.

specification/application_service_api.rst

@@ -218,6 +218,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
@@ -314,6 +317,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
 ~~~~~~~~~~~~