3PE lookup service

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.
@@ -91,7 +92,13 @@ paths:
               }
           schema:
             type: object
-
+        500:
+          description: There was a problem completing the request.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
   "/rooms/{roomAlias}":
     get:
       summary: Query if a room alias should exist on the application service.
@@ -147,7 +154,14 @@ paths:
             Optional error information can be included in the body of this response.
           examples:
             application/json: {
-                "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+                "errcode": "M_NOT_FOUND"
+              }
+          schema:
+            type: object
+        500:
+          description: There was a problem completing the request.
+          examples:
+            application/json: {
               }
           schema:
             type: object
@@ -203,7 +217,378 @@ paths:
             Optional error information can be included in the body of this response.
           examples:
             application/json: {
-                "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+                "errcode": "M_NOT_FOUND"
+              }
+          schema:
+            type: object
+        500:
+          description: There was a problem completing the request.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
+  "/_matrix/app/unstable/thirdparty/{protocol}":
+    get:
+      summary: Retrieve metadata about a specific protocol that the application service supports.
+      description: |-
+        This API is called by the HS when it wants to present clients with
+        specific information about the various thirdparty networks that an AS
+        supports.
+      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.
+          examples:
+            application/json: {
+                "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",
+                    }
+                  }
+                ]
+              }
+          schema:
+            type: object
+        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:
+            type: object
+        403:
+          description: |-
+            The credentials supplied by the homeserver were rejected.
+          examples:
+            application/json: {
+                "errcode": "M_FORBIDDEN"
+              }
+          schema:
+            type: object
+        404:
+          description: No protocol was found with the given path.
+          examples:
+            application/json: {
+                "errcode": "M_NOT_FOUND"
+              }
+          schema:
+            type: object
+        500:
+          description: There was a problem completing the request.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
+  "/_matrix/app/unstable/thirdparty/user/{protocol}":
+    get:
+      summary: Retrieve the Matrix ID of a corresponding thirdparty user.
+      description: |-
+        This API is called by the HS in order to retrieve a Matrix ID linked
+        to a user on the external 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 IDs found with the given parameters.
+          examples:
+            application/json: [{
+                "userid": "@_gitter_jim:matrix.org",
+                "protocol": "gitter",
+                "fields": {
+                  "user": "jim"
+                }
+              }]
+          schema:
+            type: array
+            description: Matched users.
+            items:
+              type: object
+              title: User
+        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:
+            type: object
+        403:
+          description: |-
+            The credentials supplied by the homeserver were rejected.
+          examples:
+            application/json: {
+                "errcode": "M_FORBIDDEN"
+              }
+          schema:
+            type: object
+        404:
+          description: No users were found with the given parameters.
+          examples:
+            application/json: {
+                "errcode": "M_NOT_FOUND"
+              }
+          schema:
+            type: object
+        500:
+          description: There was a problem completing the request.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
+  "/_matrix/app/unstable/thirdparty/location/{protocol}":
+    get:
+      summary: Retreive Matrix-side portals rooms leading to a thirdparty 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 3PN. Each has the Matrix room alias string, an identifier for
+        the particular 3PN 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 thirdparty network.
+          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 thirdparty location.
+      responses:
+        200:
+          description: At least one portal room was found.
+          examples:
+            application/json: [{
+                "alias": "#freenode_#matrix:matrix.org",
+                "protocol": "irc",
+                "fields": {
+                  "network": "freenode",
+                  "channel": "#matrix"
+                }
+              }]
+          schema:
+            type: array
+            description: |-
+              Array of portal rooms leading to the requested thirdparty
+              location.
+            items:
+              type: object
+              title: Portal Room
+        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:
+            type: object
+        403:
+          description: |-
+            The credentials supplied by the homeserver were rejected.
+          examples:
+            application/json: {
+                "errcode": "M_FORBIDDEN"
               }
           schema:
             type: object
+        404:
+          description: No mappings were found with the given parameters.
+          examples:
+            application/json: {
+                "errcode": "M_NOT_FOUND"
+              }
+          schema:
+            type: object
+        500:
+          description: There was a problem completing the request.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
+  "/_matrix/app/unstable/thirdparty/location":
+    get:
+      summary: Reverse-lookup thirdparty locations given a Matrix room alias.
+      description: |-
+        Retreive an array of thirdparty network locations from a Matrix room
+        alias.
+      operationId: queryLocationByAlias
+      parameters:
+       - in: path
+         name: alias
+         type: string
+         description: The Matrix room alias to look up.
+      responses:
+        200:
+          description: |-
+            All found thirdparty locations. Same response format as the
+            forward lookup response.
+          examples:
+            application/json: [{
+                "alias": "#freenode_#matrix:matrix.org",
+                "protocol": "irc",
+                "fields": {
+                  "network": "freenode",
+                  "channel": "#matrix"
+                }
+              }]
+          schema:
+            type: array
+            description: Matched thirdparty locations.
+            items:
+              type: object
+              title: Location
+        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:
+            type: object
+        403:
+          description: |-
+            The credentials supplied by the homeserver were rejected.
+          examples:
+            application/json: {
+                "errcode": "M_FORBIDDEN"
+              }
+          schema:
+            type: object
+        404:
+          description: No mappings were found with the given parameters.
+          examples:
+            application/json: {
+                "errcode": "M_NOT_FOUND"
+              }
+          schema:
+            type: object
+        500:
+          description: There was a problem completing the request.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
+  "/_matrix/app/unstable/thirdparty/user":
+    get:
+      summary: Reverse-lookup thirdparty users given a Matrix ID.
+      description: |-
+        Retreive an array of thirdparty users from a Matrix ID.
+      operationId: queryUserByID
+      paramters:
+        - in: path
+          name: userid
+          type: string
+          description: The Matrix ID to look up.
+      responses:
+        200:
+          description: |-
+            An array of thirdparty users.
+          examples:
+            application/json: [{
+                "userid": "@_gitter_jim:matrix.org",
+                "protocol": "gitter",
+                "fields": {
+                  "user": "jim"
+                }
+              }]
+          schema:
+            type: array
+            description: Matched thirdparty users
+            items:
+              type: object
+              title: User
+        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:
+            type: object
+        403:
+          description: |-
+            The credentials supplied by the homeserver were rejected.
+          examples:
+            application/json: {
+                "errcode": "M_FORBIDDEN"
+              }
+          schema:
+            type: object
+        404:
+          description: No mappings were found with the given parameters.
+          examples:
+            application/json: {
+                "errcode": "M_NOT_FOUND"
+              }
+          schema:
+            type: object
+        500:
+          description: There was a problem completing the request.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object

changelogs/client_server.rst

@@ -11,6 +11,18 @@ Unreleased changes
       (`#1110 <https://github.com/matrix-org/matrix-doc/pull/1110>`_).
     - ``POST /delete_devices``
       (`#1239 <https://github.com/matrix-org/matrix-doc/pull/1239>`_).
+    - ``GET /thirdparty/protocols``
+      (`#1353 <https://github.com/matrix-org/matrix-doc/pull/1353>`_).
+    - ``GET /thirdparty/protocol/{protocol}``
+      (`#1353 <https://github.com/matrix-org/matrix-doc/pull/1353>`_).
+    - ``GET /thirdparty/location/{protocol}``
+      (`#1353 <https://github.com/matrix-org/matrix-doc/pull/1353>`_).
+    - ``GET /thirdparty/user/{protocol}``
+      (`#1353 <https://github.com/matrix-org/matrix-doc/pull/1353>`_).
+    - ``GET /thirdparty/location``
+      (`#1353 <https://github.com/matrix-org/matrix-doc/pull/1353>`_).
+    - ``GET /thirdparty/user``
+      (`#1353 <https://github.com/matrix-org/matrix-doc/pull/1353>`_).
 
   - Sticker messages:
     - Add sticker message event definition.

specification/targets.yaml

@@ -12,6 +12,7 @@ targets:
       - { 1: modules.rst }
       - { 2: feature_profiles.rst }
       - { 2: "group:modules" }  # reference a group of files
+      - { 1: thirdparty_lookup.rst }
     version_label: "%CLIENT_RELEASE_LABEL%"
   application_service:
     files: