From cc3724b54a44bef1ee26577e74b2f167aebdcc2a Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 5 Jul 2018 11:55:25 +0100 Subject: [PATCH] fix indentation, error messages. add rest of PR --- .../application_service.yaml | 331 ++++---- api/client-server/third_party_lookup.yaml | 338 ++++++++ changelogs/client_server.rst | 2 - specification/proposals.rst | 770 +++++++++++++++++- specification/targets.yaml | 2 +- specification/third_party_lookup.rst | 26 + 6 files changed, 1306 insertions(+), 163 deletions(-) create mode 100644 api/client-server/third_party_lookup.yaml create mode 100644 specification/third_party_lookup.rst diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index a0713d45..5efc058b 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -30,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 - batch of events) to the AS. + This API is called by the homeserver when it wants to push an event + (or batch of events) to the application service. operationId: sendTransaction parameters: - in: path @@ -48,33 +48,33 @@ paths: schema: type: object example: { - "events": [ - { - "age": 32, - "content": { - "body": "incoming message", - "msgtype": "m.text" - }, - "event_id": "$14328055551tzaee:localhost", - "origin_server_ts": 1432804485886, - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "type": "m.room.message", - "user_id": "@bob:localhost" + "events": [ + { + "age": 32, + "content": { + "body": "incoming message", + "msgtype": "m.text" }, - { - "age": 1984, - "content": { - "body": "another incoming message", - "msgtype": "m.text" - }, - "event_id": "$1228055551ffsef:localhost", - "origin_server_ts": 1432804485886, - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "type": "m.room.message", - "user_id": "@bob:localhost" - } - ] - } + "event_id": "$14328055551tzaee:localhost", + "origin_server_ts": 1432804485886, + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "type": "m.room.message", + "user_id": "@bob:localhost" + }, + { + "age": 1984, + "content": { + "body": "another incoming message", + "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: @@ -89,14 +89,14 @@ paths: description: The transaction was processed successfully. examples: application/json: { - } + } schema: type: object 500: description: There was a problem completing the request. examples: application/json: { - } + } schema: type: object "/rooms/{roomAlias}": @@ -126,7 +126,7 @@ paths: before responding. examples: application/json: { - } + } schema: type: object 401: @@ -135,8 +135,8 @@ 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 403: @@ -144,8 +144,8 @@ paths: The credentials supplied by the homeserver were rejected. examples: application/json: { - "errcode": "M_FORBIDDEN" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } schema: type: object 404: @@ -154,15 +154,15 @@ paths: Optional error information can be included in the body of this response. examples: application/json: { - "errcode": "M_NOT_FOUND" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } schema: type: object 500: description: There was a problem completing the request. examples: application/json: { - } + } schema: type: object "/users/{userId}": @@ -189,7 +189,7 @@ paths: service MUST create the user using the client-server API. examples: application/json: { - } + } schema: type: object 401: @@ -198,8 +198,8 @@ 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 403: @@ -207,8 +207,8 @@ paths: The credentials supplied by the homeserver were rejected. examples: application/json: { - "errcode": "M_FORBIDDEN" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } schema: type: object 404: @@ -217,24 +217,24 @@ paths: Optional error information can be included in the body of this response. examples: application/json: { - "errcode": "M_NOT_FOUND" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_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. + 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 @@ -249,33 +249,33 @@ paths: 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" - } + "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" }, - "instances": [ - { - "desc": "Freenode", - "icon": "mxc://example.org/JkLmNoPq", - "fields": { - "network": "freenode.net", - } + "channel": { + "regexp": "#[^\\s]+", + "placeholder": "#foobar" + } + }, + "instances": [ + { + "desc": "Freenode", + "icon": "mxc://example.org/JkLmNoPq", + "fields": { + "network": "freenode.net", } - ] - } + } + ] + } schema: type: object 401: @@ -284,8 +284,8 @@ 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 403: @@ -293,30 +293,30 @@ paths: The credentials supplied by the homeserver were rejected. examples: application/json: { - "errcode": "M_FORBIDDEN" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } schema: type: object 404: description: No protocol was found with the given path. examples: application/json: { - "errcode": "M_NOT_FOUND" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_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. + summary: Retrieve the Matrix ID of a corresponding third party user. description: |- - This API is called by the HS in order to retrieve a Matrix ID linked + This API is called by the homeserver in order to retrieve a Matrix ID linked to a user on the external service, given a set of user parameters. operationId: queryUserByProtocol parameters: @@ -331,32 +331,47 @@ paths: name: field1, field2... type: string description: |- - One or more custom fields that are passed to the AS to help identify the user. + One or more custom fields that are passed to the application + service 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" - } - }] + "userid": "@_gitter_jim:matrix.org", + "protocol": "gitter", + "fields": { + "user": "jim" + } + }] schema: type: array description: Matched users. items: type: object title: User + properties: + userid: + type: string + description: The Matrix ID of the matched user. + protocol: + type: string + description: The third party protocol. + fields: + type: object + description: The third party network fields used to identify this user. + properties: + user: + type: string + description: An example field, in this case the username for a Gitter 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" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } schema: type: object 403: @@ -364,67 +379,67 @@ paths: The credentials supplied by the homeserver were rejected. examples: application/json: { - "errcode": "M_FORBIDDEN" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } schema: type: object 404: description: No users were found with the given parameters. examples: application/json: { - "errcode": "M_NOT_FOUND" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_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. + summary: Retreive Matrix-side portal 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 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. + 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 thirdparty network. + description: The protocol used to communicate to the third party 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. + 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. examples: application/json: [{ - "alias": "#freenode_#matrix:matrix.org", - "protocol": "irc", - "fields": { - "network": "freenode", - "channel": "#matrix" - } - }] + "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 + Array of portal rooms leading to the requested third party location. items: type: object @@ -435,8 +450,8 @@ 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 403: @@ -444,54 +459,54 @@ paths: The credentials supplied by the homeserver were rejected. examples: application/json: { - "errcode": "M_FORBIDDEN" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } schema: type: object 404: description: No mappings were found with the given parameters. examples: application/json: { - "errcode": "M_NOT_FOUND" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_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. + summary: Reverse-lookup third party locations given a Matrix room alias. description: |- - Retreive an array of thirdparty network locations from a Matrix room + Retreive an array of third party network locations from a Matrix room alias. operationId: queryLocationByAlias parameters: - - in: path + - in: query name: alias type: string description: The Matrix room alias to look up. responses: 200: description: |- - All found thirdparty locations. Same response format as the + All found third party locations. Same response format as the forward lookup response. examples: application/json: [{ - "alias": "#freenode_#matrix:matrix.org", - "protocol": "irc", - "fields": { - "network": "freenode", - "channel": "#matrix" - } - }] + "alias": "#freenode_#matrix:matrix.org", + "protocol": "irc", + "fields": { + "network": "freenode", + "channel": "#matrix" + } + }] schema: type: array - description: Matched thirdparty locations. + description: Matched third party locations. items: type: object title: Location @@ -501,8 +516,8 @@ 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 403: @@ -510,51 +525,51 @@ paths: The credentials supplied by the homeserver were rejected. examples: application/json: { - "errcode": "M_FORBIDDEN" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } schema: type: object 404: description: No mappings were found with the given parameters. examples: application/json: { - "errcode": "M_NOT_FOUND" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_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. + summary: Reverse-lookup third party users given a Matrix ID. description: |- - Retreive an array of thirdparty users from a Matrix ID. + Retreive an array of third party users from a Matrix ID. operationId: queryUserByID paramters: - - in: path + - in: query name: userid type: string description: The Matrix ID to look up. responses: 200: description: |- - An array of thirdparty users. + An array of third party users. examples: application/json: [{ - "userid": "@_gitter_jim:matrix.org", - "protocol": "gitter", - "fields": { - "user": "jim" - } - }] + "userid": "@_gitter_jim:matrix.org", + "protocol": "gitter", + "fields": { + "user": "jim" + } + }] schema: type: array - description: Matched thirdparty users + description: Matched third party users items: type: object title: User @@ -564,8 +579,8 @@ 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 403: @@ -573,22 +588,22 @@ paths: The credentials supplied by the homeserver were rejected. examples: application/json: { - "errcode": "M_FORBIDDEN" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } schema: type: object 404: description: No mappings were found with the given parameters. examples: application/json: { - "errcode": "M_NOT_FOUND" - } + "errcode": "COM.EXAMPLE.MYAPPSERVICE_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/api/client-server/third_party_lookup.yaml b/api/client-server/third_party_lookup.yaml new file mode 100644 index 00000000..41b5df16 --- /dev/null +++ b/api/client-server/third_party_lookup.yaml @@ -0,0 +1,338 @@ +# 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 +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. + examples: + application/json: { + "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": {} + } + ] + } + } + schema: + type: object + "/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. + 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 + 404: + description: The protocol is unknown + examples: + application/json: { + "errcode": "M_NOT_FOUND" + } + schema: + type: object + "/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: field1, field2... + 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. + 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 third party + location. + items: + type: object + title: Portal Room + 404: + description: The Matrix room alias was not found + examples: + application/json: { + "errcode": "M_NOT_FOUND" + } + schema: + type: object + "/thirdparty/user/{protocol}": + get: + summary: Retrieve the Matrix ID of a corresponding third party user. + description: |- + Retrieve a Matrix 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 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 + properties: + userid: + type: string + description: The Matrix ID of the matched user. + protocol: + type: string + description: The third party protocol. + fields: + type: object + description: The third party network fields used to identify this user. + properties: + user: + type: string + description: An example field, in this case the username for a Gitter user. + 404: + description: The Matrix ID was not found + examples: + application/json: { + "errcode": "M_NOT_FOUND" + } + schema: + type: object + "/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: path + name: alias + type: string + description: The Matrix room alias to look up. + responses: + 200: + description: |- + All found third party 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 third party locations. + items: + type: object + title: Location + 404: + description: The Matrix room alias was not found + examples: + application/json: { + "errcode": "M_NOT_FOUND" + } + schema: + type: object + "/thirdparty/user": + get: + summary: Reverse-lookup third party users given a Matrix ID. + description: |- + Retreive an array of third party 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 third party users. + examples: + application/json: [{ + "userid": "@_gitter_jim:matrix.org", + "protocol": "gitter", + "fields": { + "user": "jim" + } + }] + schema: + type: array + description: Matched third party users + items: + type: object + title: User + 404: + description: The Matrix ID was not found + examples: + application/json: { + "errcode": "M_NOT_FOUND" + } + schema: + type: object \ No newline at end of file diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index f7e94dbe..7f31aa75 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -11,8 +11,6 @@ Unreleased changes (`#1110 `_). - ``POST /delete_devices`` (`#1239 `_). - - ``GET /thirdparty/protocols`` - (`#1353 `_). - ``GET /thirdparty/protocol/{protocol}`` (`#1353 `_). - ``GET /thirdparty/location/{protocol}`` diff --git a/specification/proposals.rst b/specification/proposals.rst index 371850ab..d04edfa8 100644 --- a/specification/proposals.rst +++ b/specification/proposals.rst @@ -1,6 +1,772 @@ Tables of Tracked Proposals --------------------------- -This file is autogenerated by a jenkins build process +proposal-wip +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -View the current live version `at https://matrix.org/docs/spec/proposals `_ +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documentation + - Author + - Shepherd + - PRs + * - `MSC455 `_ + - Do we want to specify a matrix:// URI scheme for rooms? (SPEC-5) + - 2014-09-15 + - 2018-05-15 + - `455-1 `_ + - `@KitsuneRal`_ + - None + - + * - `MSC586 `_ + - Federation API for canonicalising MXIDs + - 2014-10-27 + - 2018-05-15 + - `586-1 `_ + - `@ara4n`_ + - None + - + * - `MSC489 `_ + - Extensible Profiles. (SPEC-93) + - 2015-01-19 + - 2018-05-15 + - `489-1 `_ + - `@erikjohnston`_ + - None + - + * - `MSC1196 `_ + - Matrix Escape Hatch (Versioned Rooms) + - 2015-10-22 + - 2018-05-15 + - `1196-1 `_ + - `@leonerd`_ + - None + - + * - `MSC1148 `_ + - Support for websockets + - 2015-11-16 + - 2018-06-04 + - `1148-1 `_, `1148-2 `_ + - `@richvdh`_, `@krombel`_ + - None + - + * - `MSC1238 `_ + - Push to Talk + - 2016-04-13 + - 2018-05-15 + - `1238-1 `_ + - `@aviraldg`_ + - None + - `PR#310`_ + * - `MSC1198 `_ + - Threading API + - 2016-05-23 + - 2018-05-15 + - `1198-1 `_ + - `@Half-Shot`_ + - None + - + * - `MSC1207 `_ + - Publishing Room Lists for 3rd party networks + - 2016-10-21 + - 2018-05-31 + - `1207-1 `_ + - `@erikjohnston`_ + - None + - + * - `MSC441 `_ + - Support for Reactions / Aggregations + - 2016-12-25 + - 2018-05-15 + - `441-1 `_ + - `@pik`_ + - `@ara4n`_ + - + * - `MSC1237 `_ + - Improving m.location with GeoJSON and accuracy + - 2017-05-19 + - 2018-05-15 + - `1237-1 `_ + - `@Half-Shot`_ + - None + - `PR#919`_ + * - `MSC971 `_ + - Add groups stuff to spec + - 2017-08-10 + - 2018-05-20 + - `971-1 `_, `971-2 `_, `971-3 `_ + - `@erikjohnston`_ + - None + - + * - `MSC1215 `_ + - Groups as Rooms + - 2017-10-17 + - 2018-05-15 + - `1215-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1217 `_ + - Visibility of groups to group members and their non-members + - 2017-10-30 + - 2018-05-15 + - `1217-1 `_ + - `@lampholder`_ + - None + - + * - `MSC1218 `_ + - Bridging group membership with 3rd party group sources + - 2017-11-15 + - 2018-05-15 + - `1218-1 `_ + - `@lukebarnard1`_ + - None + - + * - `MSC1219 `_ + - Proposal for storing megolm keys serverside + - 2017-11-23 + - 2018-05-15 + - `1219-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1221 `_ + - Improving Presence + - 2017-12-26 + - 2018-05-24 + - `1221-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1222 `_ + - Pushing updates about Groups (Communities) to clients + - 2018-01-02 + - 2018-05-24 + - `1222-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1225 `_ + - Extensible event types & fallback in Matrix + - 2018-02-18 + - 2018-05-15 + - `1225-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1206 `_ + - Proposal for improved bot support + - 2018-03-14 + - 2018-06-08 + - `1206-1 `_ + - `@turt2live`_ + - None + - + * - `MSC1228 `_ + - Removing MXIDs from events + - 2018-04-19 + - 2018-05-15 + - `1228-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1231 `_ + - Handling Consent for Privacy Policy + - 2018-05-02 + - 2018-05-15 + - `1231-1 `_ + - `@neilisfragile`_ + - None + - + * - `MSC1267 `_ + - Interactive Key Verification + - 2018-05-28 + - 2018-05-28 + - `1267-1 `_ + - `@uhoreg`_ + - None + - + * - `MSC1280 `_ + - Mechanisms for communicating erasure requests to bots and federated homeservers + - 2018-06-05 + - 2018-06-05 + - `1280-1 `_ + - `@richvdh`_ + - None + - + * - `MSC688 `_ + - Calculate room names server-side + - 2018-06-10 + - 2018-06-15 + - `688-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1324 `_ + - Custom protocol definitions for application services + - 2018-06-20 + - 2018-06-20 + - `1324-1 `_ + - `@anoadragon453`_ + - None + - + * - `MSC1323 `_ + - AS traffic rate-limiting + - 2018-06-20 + - 2018-07-03 + - `1323-1 `_ + - `@anoadragon453`_ + - None + - + * - `MSC1322 `_ + - Mechanism to communicate 3PID binding updates or deletions to homeservers + - 2018-06-20 + - 2018-06-20 + - `1322-1 `_ + - `@babolivier`_ + - None + - + + + +proposal-ready-for-review +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documentation + - Author + - Shepherd + - PRs + * - `MSC1227 `_ + - Proposal for lazy-loading room members to improve initial sync speed and client RAM usage + - 2018-03-05 + - 2018-06-10 + - `1227-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1206 `_ + - Proposal for improved bot support + - 2018-03-14 + - 2018-06-08 + - `1206-1 `_ + - `@turt2live`_ + - None + - + * - `MSC1256 `_ + - Custom emoji and sticker packs in matrix + - 2018-05-23 + - 2018-05-24 + - `1256-1 `_ + - `@turt2live`_ + - None + - + * - `MSC1270 `_ + - Proposal Add /_matrix/media/v1/resolve_url to Client-Server API: download and preview urls in the clients despite CORS + - 2018-05-31 + - 2018-06-19 + - `1270-1 `_ + - `@oivoodoo`_ + - None + - + * - `MSC701 `_ + - Auth for content repo (and enforcing GDPR erasure) + - 2018-06-04 + - 2018-06-07 + - `701-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1304 `_ + - Proposal to simplify the auth rules of m.room.power_level events. + - 2018-06-13 + - 2018-06-14 + - `1304-1 `_ + - `@richvdh`_, `@ara4n`_ + - None + - + * - `MSC1301 `_ + - Proposal for improving authorization for the matrix profile API + - 2018-06-13 + - 2018-06-13 + - `1301-1 `_ + - `@turt2live`_ + - None + - + * - `MSC1309 `_ + - Proposal for an application service management API + - 2018-06-14 + - 2018-06-15 + - `1309-1 `_ + - `@turt2live`_ + - None + - + * - `MSC1308 `_ + - Proposal for speeding up review of simple spec changes + - 2018-06-14 + - 2018-06-24 + - + - `@ara4n`_ + - None + - + * - `MSC1306 `_ + - Proposal to filter out traffic to Appservices based on filters + - 2018-06-14 + - 2018-06-14 + - `1306-1 `_ + - `@Half-Shot`_ + - None + - + + + +proposal-in-review +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documentation + - Author + - Shepherd + - PRs + * - `MSC1194 `_ + - A way for HSes to remove bindings from ISes (aka unbind) + - 2018-05-09 + - 2018-06-05 + - `1194-1 `_ + - `@dbkr`_ + - None + - + + + +proposal-passed-review +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documentation + - Author + - Shepherd + - PRs + * - `MSC433 `_ + - Support for discovering API endpoints via .well-known URIs (SPEC-121) + - 2015-03-08 + - 2018-07-01 + - `433-1 `_, `433-2 `_ + - `@maxidor`_, `others`_ + - `@uhoreg`_ + - + * - `MSC1226 `_ + - State Reset mitigation proposal + - 2018-02-20 + - 2018-05-15 + - `1226-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1229 `_ + - Mitigating abuse of the event depth parameter over federation + - 2018-04-30 + - 2018-05-15 + - `1229-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1232 `_ + - Media limits API + - 2018-05-04 + - 2018-06-21 + - `1232-1 `_ + - `@Half-Shot`_ + - None + - `PR#1189`_ + * - `MSC1236 `_ + - Matrix Widget API v2 + - 2018-05-13 + - 2018-05-15 + - `1236-1 `_ + - `@rxl881`_ + - None + - + + + +spec-pr-missing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documentation + - Author + - Shepherd + - PRs + * - `MSC1200 `_ + - Configuration of E2E encryption in a room + - 2016-06-16 + - 2018-05-31 + - `1200-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1201 `_ + - Device Management API + - 2016-07-14 + - 2018-05-15 + - `1201-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1203 `_ + - 3rd Party Entity lookup API + - 2016-07-21 + - 2018-07-02 + - `1203-1 `_ + - `@leonerd`_ + - None + - + * - `MSC1208 `_ + - Encrypted attachment format + - 2016-10-26 + - 2018-05-15 + - `1208-1 `_ + - `@NegativeMjark`_ + - None + - + * - `MSC739 `_ + - Reporting inappropriate content in Matrix + - 2016-11-21 + - 2018-05-31 + - `739-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1211 `_ + - Megolm session export format + - 2017-01-03 + - 2018-05-15 + - `1211-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1212 `_ + - Device List Update Stream + - 2017-01-18 + - 2018-05-15 + - `1212-1 `_ + - `@richvdh`_ + - None + - + * - `MSC829 `_ + - Need to spec msisdn login API + - 2017-03-08 + - 2018-05-15 + - `829-1 `_ + - `@dbkr`_ + - None + - + * - `MSC855 `_ + - spec m.login.msisdn UI auth type + - 2017-03-24 + - 2018-05-15 + - `855-1 `_ + - `@dbkr`_ + - None + - + * - `MSC910 `_ + - Add new Read Marker API to docs + - 2017-05-08 + - 2018-05-15 + - + - `@lukebarnard1`_ + - None + - + * - `MSC1067 `_ + - Spec @mentions + - 2017-07-14 + - 2018-05-15 + - `1067-1 `_ + - `@lukebarnard1`_ + - None + - + * - `MSC1214 `_ + - Related Groups (i.e. flair) + - 2017-10-03 + - 2018-05-15 + - `1214-1 `_ + - `@lukebarnard1`_ + - None + - + * - `MSC1033 `_ + - Doc @room notifications + - 2017-10-23 + - 2018-05-31 + - + - `@dbkr`_ + - None + - + * - `MSC1183 `_ + - Document key-share requests + - 2018-04-30 + - 2018-05-31 + - `1183-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1230 `_ + - Temporary mitigation for depth parameter abuse + - 2018-05-01 + - 2018-05-15 + - `1230-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1234 `_ + - Rich Replies format + - 2018-05-12 + - 2018-05-18 + - `1234-1 `_ + - `@t3chguy`_ + - None + - + + + +merged +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documentation + - Author + - Shepherd + - PRs + * - `MSC1197 `_ + - Ignoring Users + - 2016-05-03 + - 2018-05-18 + - `1197-1 `_ + - `@erikjohnston`_ + - None + - `PR#1142`_ + * - `MSC1199 `_ + - Notifications API + - 2016-05-23 + - 2018-06-25 + - `1199-1 `_ + - `@dbkr`_ + - None + - + * - `MSC1204 `_ + - Access Token Semantics (refresh and macaroons) - aka Auth Sept 2016 Edition + - 2016-09-29 + - 2018-06-25 + - `1204-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1205 `_ + - Proposal for multi-device deletion API + - 2016-10-12 + - 2018-06-25 + - `1205-1 `_ + - `@richvdh`_ + - None + - `PR#1239`_ + * - `MSC953 `_ + - Add /user_directory/search API + - 2017-05-31 + - 2018-05-10 + - `953-1 `_ + - `@erikjohnston`_ + - None + - + * - `MSC1233 `_ + - A proposal for organising spec proposals + - 2018-05-10 + - 2018-06-25 + - `1233-1 `_ + - `@ara4n`_ + - None + - `PR#1240`_ + + + +abandoned +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documentation + - Author + - Shepherd + - PRs + * - `MSC531 `_ + - Homeservers as OAuth authorization endpoints (resource owners) (SPEC-206) + - 2015-07-25 + - 2018-05-15 + - `531-1 `_ + - `@Kegsay`_ + - None + - + * - `MSC1202 `_ + - Profile Personae + - 2016-07-15 + - 2018-05-15 + - `1202-1 `_ + - `@erikjohnston`_ + - None + - + * - `MSC1209 `_ + - Server Side Profile API + - 2016-11-01 + - 2018-05-15 + - `1209-1 `_ + - `@erikjohnston`_ + - None + - + * - `MSC1213 `_ + - Set defaults for m.federate + - 2017-04-10 + - 2018-05-18 + - `1213-1 `_ + - `@psaavedra`_ + - None + - + + + +obsolete +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documentation + - Author + - Shepherd + - PRs + * - `MSC1223 `_ + - Replies event format + - 2018-02-01 + - 2018-05-15 + - `1223-1 `_ + - `@t3chguy`_ + - None + - + * - `MSC1224 `_ + - Replies - next steps + - 2018-02-03 + - 2018-05-15 + - `1224-1 `_ + - `@t3chguy`_ + - None + - + * - `MSC1235 `_ + - Proposal for Calendar Events + - 2018-02-06 + - 2018-05-15 + - `1235-1 `_ + - `@Half-Shot`_ + - None + - + * - `MSC1220 `_ + - Rich quoting proposal + - 2018-05-10 + - 2018-05-15 + - `1220-1 `_ + - `@t3chguy`_ + - None + - + + + + + +.. _@rxl881: https://github.com/rxl881 +.. _@turt2live: https://github.com/turt2live +.. _@erikjohnston: https://github.com/erikjohnston +.. _@anoadragon453: https://github.com/anoadragon453 +.. _@t3chguy: https://github.com/t3chguy +.. _@Kegsay: https://github.com/Kegsay +.. _@KitsuneRal: https://github.com/KitsuneRal +.. _@leonerd: https://github.com/leonerd +.. _@psaavedra: https://github.com/psaavedra +.. _@ara4n: https://github.com/ara4n +.. _@krombel: https://github.com/krombel +.. _@maxidor: https://github.com/maxidor +.. _@uhoreg: https://github.com/uhoreg +.. _@pik: https://github.com/pik +.. _@neilisfragile: https://github.com/neilisfragile +.. _@babolivier: https://github.com/babolivier +.. _@lukebarnard1: https://github.com/lukebarnard1 +.. _others: https://github.com/thers +.. _@Half-Shot: https://github.com/Half-Shot +.. _@aviraldg: https://github.com/aviraldg +.. _@oivoodoo: https://github.com/oivoodoo +.. _@richvdh: https://github.com/richvdh +.. _@NegativeMjark: https://github.com/NegativeMjark +.. _@lampholder: https://github.com/lampholder +.. _@dbkr: https://github.com/dbkr +.. _PR#1189: https://github.com/matrix-org/matrix-doc/pull/1189 +.. _PR#310: https://github.com/matrix-org/matrix-doc/pull/310 +.. _PR#1142: https://github.com/matrix-org/matrix-doc/pull/1142 +.. _PR#1239: https://github.com/matrix-org/matrix-doc/pull/1239 +.. _PR#1240: https://github.com/matrix-org/matrix-doc/pull/1240 +.. _PR#919: https://github.com/matrix-org/matrix-doc/pull/919 \ No newline at end of file diff --git a/specification/targets.yaml b/specification/targets.yaml index c6c9cd23..96199d29 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -12,7 +12,7 @@ targets: - { 1: modules.rst } - { 2: feature_profiles.rst } - { 2: "group:modules" } # reference a group of files - - { 1: thirdparty_lookup.rst } + - { 1: third_party_lookup.rst } version_label: "%CLIENT_RELEASE_LABEL%" application_service: files: diff --git a/specification/third_party_lookup.rst b/specification/third_party_lookup.rst new file mode 100644 index 00000000..1279f9fe --- /dev/null +++ b/specification/third_party_lookup.rst @@ -0,0 +1,26 @@ +Application Services +==================== + +An application service is a separate program that interacts with a homeserver +and provides various bits of functionality that would otherwise not make +sense to include directly in the homeserver. This ranges from bots, which can +often be interacted with, to bridges, which allow Matrix users to communicate +with users on third party networks. The following describes endpoints that a +Matrix client can use to interact with an application service through the +facilitation of the homeserver. + +Third Party Lookups +------------------ + +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. + +In order for a client to join one of these bridged rooms, or communicate +directly with a user on a third party network, the following endpoints can be +used. + +{{third_party_lookup_cs_http_api}} \ No newline at end of file