From d73b247688606d767667c5e80a1b35c69513c566 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 26 Jun 2018 10:57:35 +0100 Subject: [PATCH] 3PE lookup service --- .../application_service.yaml | 391 +++++++++++++++++- changelogs/client_server.rst | 12 + specification/targets.yaml | 1 + 3 files changed, 401 insertions(+), 3 deletions(-) diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index c39ce198..a0713d45 100644 --- a/api/application-service/application_service.yaml +++ b/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 \ No newline at end of file diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index feabecab..f7e94dbe 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -11,6 +11,18 @@ Unreleased changes (`#1110 `_). - ``POST /delete_devices`` (`#1239 `_). + - ``GET /thirdparty/protocols`` + (`#1353 `_). + - ``GET /thirdparty/protocol/{protocol}`` + (`#1353 `_). + - ``GET /thirdparty/location/{protocol}`` + (`#1353 `_). + - ``GET /thirdparty/user/{protocol}`` + (`#1353 `_). + - ``GET /thirdparty/location`` + (`#1353 `_). + - ``GET /thirdparty/user`` + (`#1353 `_). - Sticker messages: - Add sticker message event definition. diff --git a/specification/targets.yaml b/specification/targets.yaml index bc9d94c8..c6c9cd23 100644 --- a/specification/targets.yaml +++ b/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: