From 069a2f74811d489e763fc152cbe386f733dec83b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 15:22:06 -0600 Subject: [PATCH 1/6] Split the query user and room APIs out to their own files --- .../application_service.yaml | 115 ------------------ api/application-service/query_room.yaml | 86 +++++++++++++ api/application-service/query_user.yaml | 83 +++++++++++++ specification/application_service_api.rst | 4 + 4 files changed, 173 insertions(+), 115 deletions(-) create mode 100644 api/application-service/query_room.yaml create mode 100644 api/application-service/query_user.yaml diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index 42c0c0cf..e5e22c9b 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -92,121 +92,6 @@ paths: } schema: type: object - "/rooms/{roomAlias}": - get: - summary: Query if a room alias should exist on the application service. - description: |- - This endpoint is invoked by the homeserver on an application service to query - the existence of a given room alias. The homeserver will only query room - aliases inside the application service's ``aliases`` namespace. The - homeserver will send this request when it receives a request to join a - room alias within the application service's namespace. - operationId: queryRoomByAlias - parameters: - - in: path - name: roomAlias - type: string - description: The room alias being queried. - required: true - x-example: "#magicforest:example.com" - responses: - 200: - description: |- - The application service indicates that this room alias exists. The - application service MUST have created a room and associated it with - the queried room alias using the client-server API. Additional - information about the room such as its name and topic can be set - before responding. - examples: - application/json: { - } - 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: - $ref: ../client-server/definitions/errors/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/errors/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" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - "/users/{userId}": - get: - summary: Query if a user should exist on the application service. - description: |- - This endpoint is invoked by the homeserver on an application service to query - the existence of a given user ID. The homeserver will only query user IDs - inside the application service's ``users`` namespace. The homeserver will - send this request when it receives an event for an unknown user ID in - the application service's namespace. - operationId: queryUserById - parameters: - - in: path - name: userId - type: string - description: The user ID being queried. - required: true - x-example: "@alice:example.com" - responses: - 200: - description: |- - The application service indicates that this user exists. The application - service MUST create the user using the client-server API. - examples: - application/json: { - } - 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: - $ref: ../client-server/definitions/errors/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/errors/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" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml "/_matrix/app/unstable/thirdparty/protocol/{protocol}": get: summary: Retrieve metadata about a specific protocol that the application service supports. diff --git a/api/application-service/query_room.yaml b/api/application-service/query_room.yaml new file mode 100644 index 00000000..e898f103 --- /dev/null +++ b/api/application-service/query_room.yaml @@ -0,0 +1,86 @@ +# 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 Application Service API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: "/" +consumes: + - application/json +produces: + - application/json +paths: + "/rooms/{roomAlias}": + get: + summary: Query if a room alias should exist on the application service. + description: |- + This endpoint is invoked by the homeserver on an application service to query + the existence of a given room alias. The homeserver will only query room + aliases inside the application service's ``aliases`` namespace. The + homeserver will send this request when it receives a request to join a + room alias within the application service's namespace. + operationId: queryRoomByAlias + parameters: + - in: path + name: roomAlias + type: string + description: The room alias being queried. + required: true + x-example: "#magicforest:example.com" + responses: + 200: + description: |- + The application service indicates that this room alias exists. The + application service MUST have created a room and associated it with + the queried room alias using the client-server API. Additional + information about the room such as its name and topic can be set + before responding. + examples: + application/json: { + } + 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: + $ref: ../client-server/definitions/errors/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/errors/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" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml diff --git a/api/application-service/query_user.yaml b/api/application-service/query_user.yaml new file mode 100644 index 00000000..4f699ad6 --- /dev/null +++ b/api/application-service/query_user.yaml @@ -0,0 +1,83 @@ +# 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 Application Service API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: "/" +consumes: + - application/json +produces: + - application/json +paths: + "/users/{userId}": + get: + summary: Query if a user should exist on the application service. + description: |- + This endpoint is invoked by the homeserver on an application service to query + the existence of a given user ID. The homeserver will only query user IDs + inside the application service's ``users`` namespace. The homeserver will + send this request when it receives an event for an unknown user ID in + the application service's namespace. + operationId: queryUserById + parameters: + - in: path + name: userId + type: string + description: The user ID being queried. + required: true + x-example: "@alice:example.com" + responses: + 200: + description: |- + The application service indicates that this user exists. The application + service MUST create the user using the client-server API. + examples: + application/json: { + } + 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: + $ref: ../client-server/definitions/errors/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/errors/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" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index b4950eac..cde22a89 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -172,6 +172,10 @@ application services MUST implement these APIs. These APIs are defined below. {{application_service_as_http_api}} +{{query_user_as_http_api}} + +{{query_room_as_http_api}} + .. _create the user: `sect:asapi-permissions`_ From 95b2b7c2bcf5249c190e3ee4b56fe9c34b8041f0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 15:30:42 -0600 Subject: [PATCH 2/6] Move query APIs to the right heading Fixes https://github.com/matrix-org/matrix-doc/issues/1325 Addresses some of https://github.com/matrix-org/matrix-doc/issues/1532 --- specification/application_service_api.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index cde22a89..824139f0 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -163,6 +163,10 @@ this request (e.g. to join a room alias). the application service about information about the entity such as room ID to room alias mappings. +{{query_user_as_http_api}} + +{{query_room_as_http_api}} + HTTP APIs +++++++++ @@ -172,10 +176,6 @@ application services MUST implement these APIs. These APIs are defined below. {{application_service_as_http_api}} -{{query_user_as_http_api}} - -{{query_room_as_http_api}} - .. _create the user: `sect:asapi-permissions`_ From 0863c5452e95518f7047d6b9ced3e7e7141885d4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 15:31:21 -0600 Subject: [PATCH 3/6] Take out the false third party network endpoints Fixes https://github.com/matrix-org/matrix-doc/issues/800 --- specification/application_service_api.rst | 75 ++--------------------- 1 file changed, 4 insertions(+), 71 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 824139f0..534f1ac0 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -268,78 +268,11 @@ normal users who attempt to create users or aliases *inside* an application service-defined namespace will receive the same ``M_EXCLUSIVE`` error code, but only if the application service has defined the namespace as ``exclusive``. -ID conventions -~~~~~~~~~~~~~~ -.. TODO-spec - - Giving HSes the freedom to namespace still feels like the Right Thing here. - - Exposing a public API provides the consistency which was the main complaint - against namespacing. - - This may have knock-on effects for the AS registration API. E.g. why don't - we let ASes specify the *URI* regex they want? - -This concerns the well-defined conventions for mapping 3P network IDs to matrix -IDs, which we expect clients to be able to do by themselves. - -User IDs -++++++++ -Matrix users may wish to directly contact a virtual user, e.g. to send an email. -The URI format is a well-structured way to represent a number of different ID -types, including: - -- MSISDNs (``tel``) -- Email addresses (``mailto``) -- IRC nicks (``irc`` - https://tools.ietf.org/html/draft-butcher-irc-url-04) -- XMPP (XEP-0032) -- SIP URIs (RFC 3261) - -As a result, virtual user IDs SHOULD relate to their URI counterpart. This -mapping from URI to user ID can be expressed in a number of ways: - -- Expose a C-S API on the HS which takes URIs and responds with user IDs. -- Munge the URI with the user ID. - -Exposing an API would allow HSes to internally map user IDs however they like, -at the cost of an extra round trip (of which the response can be cached). -Munging the URI would allow clients to apply the mapping locally, but would force -user X on service Y to always map to the same munged user ID. Considering the -exposed API could just be applying this munging, there is more flexibility if -an API is exposed. - -:: - - GET /_matrix/app/%CLIENT_MAJOR_VERSION%/user?uri=$url_encoded_uri - - Returns 200 OK: - { - user_id: - } - -Room Aliases -++++++++++++ -We may want to expose some 3P network rooms so Matrix users can join them directly, -e.g. IRC rooms. We don't want to expose every 3P network room though, e.g. -``mailto``, ``tel``. Rooms which are publicly accessible (e.g. IRC rooms) can be -exposed as an alias by the application service. Private rooms -(e.g. sending an email to someone) should not -be exposed in this way, but should instead operate using normal invite/join semantics. -Therefore, the ID conventions discussed below are only valid for public rooms which -expose room aliases. - -Matrix users may wish to join XMPP rooms (e.g. using XEP-0045) or IRC rooms. In both -cases, these rooms can be expressed as URIs. For consistency, these "room" URIs -SHOULD be mapped in the same way as "user" URIs. - -:: - - GET /_matrix/app/%CLIENT_MAJOR_VERSION%/alias?uri=$url_encoded_uri - - Returns 200 OK: - { - alias: - } - Event fields -++++++++++++ +~~~~~~~~~~~~ + +.. TODO-TravisR: Fix this section to be a general "3rd party networks" section + We recommend that any events that originated from a remote network should include an ``external_url`` field in their content to provide a way for Matrix clients to link into the 'native' client from which the event originated. From 60b8e72a67cb81b868cc74640d35455cd23c8bd1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 15:44:46 -0600 Subject: [PATCH 4/6] Minor text changes to the query APIs; Keep OpenMarket copyright The bulk of these APIs were copied from OpenMarket's work - we should preserve the copyright header. --- api/application-service/query_room.yaml | 6 +++--- api/application-service/query_user.yaml | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/api/application-service/query_room.yaml b/api/application-service/query_room.yaml index e898f103..7a5a7e54 100644 --- a/api/application-service/query_room.yaml +++ b/api/application-service/query_room.yaml @@ -1,3 +1,4 @@ +# Copyright 2016 OpenMarket Ltd # Copyright 2018 New Vector Ltd # # Licensed under the Apache License, Version 2.0 (the "License"); @@ -39,7 +40,7 @@ paths: - in: path name: roomAlias type: string - description: The room alias being queried. + description: The URL encoded room alias being queried. required: true x-example: "#magicforest:example.com" responses: @@ -51,8 +52,7 @@ paths: information about the room such as its name and topic can be set before responding. examples: - application/json: { - } + application/json: {} schema: type: object 401: diff --git a/api/application-service/query_user.yaml b/api/application-service/query_user.yaml index 4f699ad6..4d1e9f44 100644 --- a/api/application-service/query_user.yaml +++ b/api/application-service/query_user.yaml @@ -1,3 +1,4 @@ +# Copyright 2016 OpenMarket Ltd # Copyright 2018 New Vector Ltd # # Licensed under the Apache License, Version 2.0 (the "License"); @@ -33,13 +34,13 @@ paths: the existence of a given user ID. The homeserver will only query user IDs inside the application service's ``users`` namespace. The homeserver will send this request when it receives an event for an unknown user ID in - the application service's namespace. + the application service's namespace, such as a room invite. operationId: queryUserById parameters: - in: path name: userId type: string - description: The user ID being queried. + description: The URL encoded user ID being queried. required: true x-example: "@alice:example.com" responses: @@ -48,8 +49,7 @@ paths: The application service indicates that this user exists. The application service MUST create the user using the client-server API. examples: - application/json: { - } + application/json: {} schema: type: object 401: From a320c58e42664bbd558f0177bce7c4fa9d1c4cef Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 12:36:26 -0600 Subject: [PATCH 5/6] A path parameter is obviously URL encoded --- api/application-service/query_room.yaml | 2 +- api/application-service/query_user.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api/application-service/query_room.yaml b/api/application-service/query_room.yaml index 7a5a7e54..b885cb86 100644 --- a/api/application-service/query_room.yaml +++ b/api/application-service/query_room.yaml @@ -40,7 +40,7 @@ paths: - in: path name: roomAlias type: string - description: The URL encoded room alias being queried. + description: The room alias being queried. required: true x-example: "#magicforest:example.com" responses: diff --git a/api/application-service/query_user.yaml b/api/application-service/query_user.yaml index 4d1e9f44..0431b5e4 100644 --- a/api/application-service/query_user.yaml +++ b/api/application-service/query_user.yaml @@ -40,7 +40,7 @@ paths: - in: path name: userId type: string - description: The URL encoded user ID being queried. + description: The user ID being queried. required: true x-example: "@alice:example.com" responses: From 1102fc59b2dd248c5f53cb8fbf08b7577928165d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 21 Aug 2018 12:13:19 -0600 Subject: [PATCH 6/6] Spelling --- specification/application_service_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 87f15b00..602aaa92 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -286,7 +286,7 @@ Using ``/sync`` and ``/events`` Application services wishing to use ``/sync`` or ``/events`` from the Client-Server API MUST do so with a virtual user (provide a ``user_id`` via the query string). It -is expectected that the application service use the transactions pushed to it to +is expected that the application service use the transactions pushed to it to handle events rather than syncing with the user implied by ``sender_localpart``. Event fields