Merge pull request #1537 from turt2live/travis/as/user-alias-query

Clean up user and alias querying for application services

api/application-service/application_service.yaml

@@ -96,121 +96,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.

api/application-service/query_room.yaml

@@ -0,0 +1,86 @@
+# 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.
+# 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

api/application-service/query_user.yaml

@@ -0,0 +1,83 @@
+# 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.
+# 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, such as a room invite.
+      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

specification/application_service_api.rst

@@ -175,6 +175,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
 +++++++++
@@ -287,81 +291,14 @@ 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``.
 
-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: <complete user ID on local HS>
-  }
-
-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
+Event fields
+~~~~~~~~~~~~
 
-  Returns 200 OK:
-  {
-    alias: <complete room alias on local HS>
-  }
+.. TODO-TravisR: Fix this section to be a general "3rd party networks" section
 
-Event fields
-++++++++++++
 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.