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

api/application-service/application_service.yaml

@@ -1,4 +1,5 @@
 # Copyright 2016 OpenMarket Ltd
+# 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.
@@ -29,8 +30,8 @@ paths:
     put:
       summary: Send some events to the application service.
       description: |-
-        This API is called by the HS when the HS wants to push an event (or
+        This API is called by the homeserver when it wants to push an event
-        batch of events) to the AS.
+        (or batch of events) to the application service.
       operationId: sendTransaction
       parameters:
         - in: path
@@ -47,33 +48,33 @@ paths:
           schema:
             type: object
             example: {
-                "events": [
+              "events": [
-                  {
+                {
-                    "age": 32,
+                  "age": 32,
-                    "content": {
+                  "content": {
-                        "body": "incoming message",
+                      "body": "incoming message",
-                        "msgtype": "m.text"
+                      "msgtype": "m.text"
-                    },
-                    "event_id": "$14328055551tzaee:localhost",
-                    "origin_server_ts": 1432804485886,
-                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                    "type": "m.room.message",
-                    "user_id": "@bob:localhost"
                   },
-                  {
+                  "event_id": "$14328055551tzaee:localhost",
-                    "age": 1984,
+                  "origin_server_ts": 1432804485886,
-                    "content": {
+                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                        "body": "another incoming message",
+                  "type": "m.room.message",
-                        "msgtype": "m.text"
+                  "user_id": "@bob:localhost"
-                    },
+                },
-                    "event_id": "$1228055551ffsef:localhost",
+                {
-                    "origin_server_ts": 1432804485886,
+                  "age": 1984,
-                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                  "content": {
-                    "type": "m.room.message",
+                      "body": "another incoming message",
-                    "user_id": "@bob:localhost"
+                      "msgtype": "m.text"
-                  }
+                  },
-                ]
+                  "event_id": "$1228055551ffsef:localhost",
-              }
+                  "origin_server_ts": 1432804485886,
+                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                  "type": "m.room.message",
+                  "user_id": "@bob:localhost"
+                }
+              ]
+            }
             description: "Transaction informations"
             properties:
               events:
@@ -88,10 +89,9 @@ paths:
           description: The transaction was processed successfully.
           examples:
             application/json: {
-              }
+            }
           schema:
             type: object
-
   "/rooms/{roomAlias}":
     get:
       summary: Query if a room alias should exist on the application service.
@@ -119,7 +119,7 @@ paths:
             before responding.
           examples:
             application/json: {
-              }
+            }
           schema:
             type: object
         401:
@@ -128,29 +128,29 @@ paths:
             Optional error information can be included in the body of this response.
           examples:
             application/json: {
-                "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-              }
+            }
           schema:
-            type: object
+            $ref: ../client-server/definitions/error.yaml
         403:
           description: |-
             The credentials supplied by the homeserver were rejected.
           examples:
             application/json: {
-                "errcode": "M_FORBIDDEN"
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
-              }
+            }
           schema:
-            type: object
+            $ref: ../client-server/definitions/error.yaml
         404:
           description: |-
             The application service indicates that this room alias does not exist.
             Optional error information can be included in the body of this response.
           examples:
             application/json: {
-                "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
-              }
+            }
           schema:
-            type: object
+            $ref: ../client-server/definitions/error.yaml
   "/users/{userId}":
     get:
       summary: Query if a user should exist on the application service.
@@ -175,7 +175,7 @@ paths:
             service MUST create the user using the client-server API.
           examples:
             application/json: {
-              }
+            }
           schema:
             type: object
         401:
@@ -184,26 +184,266 @@ paths:
             Optional error information can be included in the body of this response.
           examples:
             application/json: {
-                "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-              }
+            }
           schema:
-            type: object
+            $ref: ../client-server/definitions/error.yaml
         403:
           description: |-
             The credentials supplied by the homeserver were rejected.
           examples:
             application/json: {
-                "errcode": "M_FORBIDDEN"
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
-              }
+            }
           schema:
-            type: object
+            $ref: ../client-server/definitions/error.yaml
         404:
           description: |-
             The application service indicates that this user does not exist.
             Optional error information can be included in the body of this response.
           examples:
             application/json: {
-                "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
-              }
+            }
           schema:
-            type: object
+            $ref: ../client-server/definitions/error.yaml
+  "/_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: queryMetadata
+      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/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/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/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: field1, field2...
+          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/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/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/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: field1, field2...
+          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/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/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/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/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/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/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/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/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/error.yaml

api/application-service/definitions/location.yaml

@@ -0,0 +1,30 @@
+# 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.
+properties:
+  alias:
+    description: An alias for a matrix room.
+    type: string
+    example: "#freenode_#matrix:matrix.org"
+  protocol:
+    description: The protocol ID that the third party location is a part of.
+    type: string
+    example: irc
+  fields:
+    description: Information used to identify this third party location.
+    type: object
+    example:
+      "network": "freenode"
+      "channel": "#matrix"
+title: Location
+type: object

api/application-service/definitions/location_batch.yaml

@@ -0,0 +1,17 @@
+# 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: array
+description: List of matched third party locations.
+items:
+  $ref: location.yaml

api/application-service/definitions/protocol.yaml

@@ -0,0 +1,79 @@
+# 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.
+properties:
+  user_fields:
+    description: Fields used to identify a third party 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.
+    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.
+    type: string
+    example: "mxc://example.org/aBcDeFgH"
+  field_types:
+    title: Field Types
+    description: All location or user fields should have an entry here.
+    type: object
+    properties:
+      fieldname:
+        title: Field Type
+        description: Definition of valid values for a field.
+        type: object
+        properties:
+          regexp:
+            description: A regular expression for validation of a field's value.
+            type: string
+          placeholder:
+            description: An placeholder serving as a valid example of the field value.
+            type: string
+    example: {
+      "network": {
+        "regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
+        "placeholder": "irc.example.org"
+      },
+      "nickname": {
+        "regexp": "[^\\s#]+",
+        "placeholder": "username"
+      },
+      "channel": {
+        "regexp": "#[^\\s]+",
+        "placeholder": "#foobar"
+      }
+    }
+  instances:
+    description: |-
+      A list of objects representing independent instances of configuration.
+      For instance multiple networks on IRC if multiple are bridged by the
+      same bridge.
+    type: array
+    items:
+      type: object
+      example: {
+        "desc": "Freenode",
+        "icon": "mxc://example.org/JkLmNoPq",
+        "fields": {
+          "network": "freenode.net",
+        }
+      }
+title: Protocol
+type: object

api/application-service/definitions/protocol_metadata.yaml

@@ -0,0 +1,66 @@
+# 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: Dictionary of supported third party protocols.
+example: {
+  "irc": {
+    "user_fields": ["network", "nickname"],
+    "location_fields": ["network", "channel"],
+    "icon": "mxc://example.org/aBcDeFgH",
+    "field_types": {
+      "network": {
+        "regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
+        "placeholder": "irc.example.org"
+      },
+      "nickname": {
+        "regexp": "[^\\s]+",
+        "placeholder": "username"
+      },
+      "channel": {
+        "regexp": "#[^\\s]+",
+        "placeholder": "#foobar"
+      }
+    },
+    "instances": [
+      {
+        "desc": "Freenode",
+        "icon": "mxc://example.org/JkLmNoPq",
+        "fields": {
+          "network": "freenode.net",
+        }
+      }
+    ]
+  },
+  "gitter": {
+    "user_fields": ["username"],
+    "location_fields": ["room"],
+    "field_types": {
+      "username": {
+        "regexp": "@[^\\s]+",
+        "placeholder": "@username"
+      },
+      "room": {
+        "regexp": "[^\\s]+\\/[^\\s]+",
+        "placeholder": "matrix-org/matrix-doc"
+      }
+    },
+    "instances": [
+      {
+        "desc": "Gitter",
+        "icon": "mxc://example.org/zXyWvUt",
+        "fields": {}
+      }
+    ]
+  }
+}

api/application-service/definitions/user.yaml

@@ -0,0 +1,31 @@
+# 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.
+
+# TODO: Change userid to user_id as a breaking change
+properties:
+  userid:
+    description: A Matrix User ID represting a third party user.
+    type: string
+    example: "@_gitter_jim:matrix.org"
+  protocol:
+    description: The protocol ID that the third party location is a part of.
+    type: string
+    example: gitter
+  fields:
+    description: Information used to identify this third party location.
+    type: object
+    example:
+      "user": "jim"
+title: Location
+type: object

api/application-service/definitions/user_batch.yaml

@@ -0,0 +1,17 @@
+# 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: array
+description: List of matched third party users.
+items:
+  $ref: user.yaml

api/client-server/search.yaml

@@ -227,6 +227,9 @@ paths:
                                   description: |-
                                     The historic profile information of the
                                     users that sent the events returned.
+
+                                    The ``string`` key is the user ID for which
+                                    the profile belongs to.
                                   additionalProperties:
                                     type: object
                                     title: User Profile
@@ -260,15 +263,24 @@ paths:
                           The current state for every room in the results.
                           This is included if the request had the
                           ``include_state`` key set with a value of ``true``.
+
+                          The ``string`` key is the room ID for which the ``State
+                          Event`` array belongs to.
                         additionalProperties:
                           type: array
                           title: Room State
                           items:
+                            type: object
                             "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
                       groups:
                         type: object
                         title: Groups
-                        description: Any groups that were requested.
+                        description: |-
+                          Any groups that were requested.
+
+                          The outer ``string`` key is the group key requested (eg: ``room_id``
+                          or ``sender``). The inner ``string`` key is the grouped value (eg: 
+                          a room's ID or a user's ID).
                         additionalProperties:
                           type: object
                           title: Group Key

api/client-server/third_party_lookup.yaml

@@ -0,0 +1,194 @@
+# 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 Third Party Lookup API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/thirdparty/protocols":
+    get:
+      summary: Retrieve metadata about all protocols that a homeserver supports.
+      description: |-
+        Fetches the overall metadata about protocols supported by the
+        homeserver. Includes both the available protocols and all fields
+        required for queries against each protocol.
+      operationId: queryMetadata
+      responses:
+        200:
+          description: The protocols supported by the homeserver.
+          schema:
+            $ref: ../application-service/definitions/protocol_metadata.yaml
+  "/thirdparty/protocol/{protocol}":
+    get:
+      summary: Retrieve metadata about a specific protocol that the homeserver supports.
+      description: |-
+        Fetches the metadata from the homeserver about a particular third party protocol.
+      operationId: queryMetadata
+      parameters:
+        - in: path
+          name: protocol
+          type: string
+          description: |-
+            The name of the protocol.
+          required: true
+          x-example: "irc"
+      responses:
+        200:
+          description: The protocol was found and metadata returned.
+          schema:
+            $ref: ../application-service/definitions/protocol.yaml
+        404:
+          description: The protocol is unknown.
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND"
+            }
+          schema:
+            $ref: definitions/error.yaml
+  "/thirdparty/location/{protocol}":
+    get:
+      summary: Retreive 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
+        objects to represent the Matrix room or rooms that represent a portal
+        to this third party network. Each has the Matrix room alias string,
+        an identifier for the particular third party network protocol, and an
+        object containing the network-specific fields that comprise this
+        identifier. It should attempt to canonicalise the identifier as much
+        as reasonably possible given the network type.
+      operationId: queryLocationByProtocol
+      parameters:
+        - in: path
+          name: protocol
+          type: string
+          description: The protocol used to communicate to the third party network.
+          required: true
+          x-example: irc
+        - in: query
+          name: searchFields
+          type: string
+          description: |-
+            One or more custom fields to help identify the third party
+            location.
+      responses:
+        200:
+          description: At least one portal room was found.
+          schema:
+            $ref: ../application-service/definitions/location_batch.yaml
+        404:
+          description: No portal rooms were found.
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND"
+            }
+          schema:
+            $ref: definitions/error.yaml
+  "/thirdparty/user/{protocol}":
+    get:
+      summary: Retrieve the Matrix User ID of a corresponding third party user.
+      description: |-
+        Retrieve a Matrix User ID linked to a user on the third party service, given
+        a set of user parameters.
+      operationId: queryUserByProtocol
+      parameters:
+        - in: path
+          name: protocol
+          type: string
+          description: |-
+            The name of the protocol.
+          required: true
+          x-example: irc
+        - in: query
+          name: field1, field2...
+          type: string
+          description: |-
+            One or more custom fields that are passed to the AS to help identify the user.
+      responses:
+        200:
+          description: The Matrix User IDs found with the given parameters.
+          schema:
+            $ref: ../application-service/definitions/user_batch.yaml
+        404:
+          description: The Matrix User ID was not found
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND"
+            }
+          schema:
+            $ref: definitions/error.yaml
+  "/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.
+          required: true
+      responses:
+        200:
+          description: |-
+            All found third party locations.
+          schema:
+            $ref: ../application-service/definitions/location_batch.yaml
+        404:
+          description: The Matrix room alias was not found
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND"
+            }
+          schema:
+            $ref: definitions/error.yaml
+  "/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.
+          required: true
+      responses:
+        200:
+          description: |-
+            An array of third party users.
+          schema:
+            $ref: ../application-service/definitions/user_batch.yaml
+        404:
+          description: The Matrix User ID was not found
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND"
+            }
+          schema:
+            $ref: definitions/error.yaml

changelogs/client_server/newsfragments/1400.clarification

@@ -0,0 +1 @@
+Clarify some of the properties on the search result

specification/feature_profiles.rst

@@ -42,6 +42,7 @@ Summary
  `Server Side Search`_                 Optional   Optional   Optional   Optional   Optional
  `Server Administration`_              Optional   Optional   Optional   Optional   Optional
  `Event Context`_                      Optional   Optional   Optional   Optional   Optional
+ `Third Party Networks`_               Optional   Optional   Optional   Optional   Optional
 ===================================== ========== ========== ========== ========== ==========
 
 *Please see each module for more details on what clients need to implement.*
@@ -57,6 +58,7 @@ Summary
 .. _Server Side Search: `module:search`_
 .. _Server Administration: `module:admin`_
 .. _Event Context: `module:event-context`_
+.. _Third Party Networks: `module:third-party-networks`_
 
 Clients
 -------

specification/modules/third_party_networks.rst

@@ -0,0 +1,20 @@
+Third Party Networks
+====================
+
+.. _module:third-party-networks:
+
+Application services can provide access to third party networks via bridging.
+This allows Matrix users to communicate with users on other communication
+platforms, with messages ferried back and forth by the application service. A
+single application service may bridge multiple third party networks, and many
+individual locations within those networks. A single third party network
+location may be bridged to multiple Matrix rooms.
+
+Third Party Lookups
+-------------------
+
+A client may wish to provide a rich interface for joining third party
+locations and connecting with third party users. Information necessary for
+such an interface is provided by third party lookups.
+
+{{third_party_lookup_cs_http_api}}

specification/targets.yaml

@@ -68,6 +68,7 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/ignore_users.rst
     - modules/stickers.rst
     - modules/report_content.rst
+    - modules/third_party_networks.rst
 
 
 title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]