Add room query API. Remove linking API.

Also add section on ID conventions which need thinking about.

drafts/as-http-api.rst

@@ -13,7 +13,8 @@ Registration API ``[Draft]``
 .. NOTE::
   - Do we really have to use regex for this? Can't we do this a nicer way?
 
-This API registers the application service with its host homeserver to offer its services.
+This API registers the application service with its host homeserver to offer its
+services.
 
 Inputs:
  - Credentials (e.g. some kind of string token)
@@ -21,7 +22,8 @@ Inputs:
  - Namespace[room aliases]
  - URL base to receive inbound comms
 Output:
- - The credentials the HS will use to query the AS with in return. (e.g. some kind of string token)
+ - The credentials the HS will use to query the AS with in return. (e.g. some 
+   kind of string token)
 Side effects:
  - The HS will start delivering events to the URL base specified if this 200s.
 API called when:
@@ -76,7 +78,8 @@ Inputs:
 Output:
  - None.
 Side effects:
- - The HS will stop delivering events to the URL base specified for this AS if this 200s.
+ - The HS will stop delivering events to the URL base specified for this AS if 
+   this 200s.
 API called when:
  - The application service wants to stop receiving all events from the HS.
  
@@ -97,7 +100,8 @@ This contains application service APIs which are used by the home server.
 User Query ``[Draft]``
 ~~~~~~~~~~~~~~~~~~~~~~
 
-This API is called by the HS to query the existence of a user on the Application Service's namespace.
+This API is called by the HS to query the existence of a user on the Application
+Service's namespace.
 
 Inputs:
  - User ID
@@ -131,109 +135,84 @@ Notes:
      }
    }
    
-Room Alias Query ``[TODO]``
+Room Alias Query ``[Draft]``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This API is called by the HS to query the existence of a room alias on the Application 
+This API is called by the HS to query the existence of a room alias on the 
-Service's namespace.
+Application Service's namespace.
 
+Inputs:
+ - Room alias
+ - HS Credentials
+Output:
+ - The current state events for the room if any.
+ - The message events for the room if any.
+Side effects:
+ - A new room will be created with the alias input if this response 200s.
+API called when:
+ - HS receives an event to join a room alias in the AS's namespace.
+Notes:
+ - This can be thought of as an ``initialSync`` but for a 3P networked room,
+   which is lazily loaded when a matrix user tries to join the room.
+ 
+::
+
+ GET /rooms/$room_alias?access_token=$hs_token
+ 
+ Returns:
+   200 : Room is recognised.
+   404 : Room not found.
+   401 : Credentials need to be supplied.
+   403 : HS credentials rejected.
+ 
+ 
+   200 OK response format
+ 
+   {
+     events: [
+       {
+         content: {
+           ...
+         },
+         user_id: "string",
+         origin_server_ts: integer,  // massaged timestamps
+         type: "string"
+       },
+       ...
+     ],
+     state: [
+       {
+         content: {
+           ...
+         },
+         user_id: "string(virtual user id)",
+         origin_server_ts: integer,
+         state_key: "string",
+         type: "string"  // e.g. m.room.name
+       },
+       ...
+     ]
+   }
 
 Pushing ``[TODO]``
 ~~~~~~~~~~~~~~~~~~
-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 HS when the HS wants to push an event (or batch of 
+events) to the AS.
 
 - Retry semantics
 - Ordering
 
 
- 
-Client -> Server -> Application Service
----------------------------------------
-This contains home server APIs which are used by the client, to communicate with
-the application service.
-
-Linking ``[Draft]``
-~~~~~~~~~~~~~~~~~~
-.. NOTE::
- - How does the application service know that the matrix user really is the virtual
-   user they claim to be? If we force an IS lookup, then this would resolve on its
-   own as anyone who wants to talk to the virtual user will do a lookup before trying
-   the application service...
- - In other words, what is preventing ``@bob:matrix.org`` masquerading as 
-   ``@.irc.freenode.alice:matrix.org``?
-
-Clients may want to link their matrix user ID to their virtual user ID. This
-API allows the AS to do this, so messages sent from the AS are sent as the client's
-user ID, instead of the virtual user ID.
-
-This is not achieved using OAuth2 or similar because the trust relationships are
-different. The application service already has a huge amount of trust from the
-home server, unlike a random third-party web app. As a result, the data flow is
-different because the third-party (the application service) is trusted by the
-authorisation entity (the home server). Furthermore, it is desirable to not have
-the clients communicate directly with the application service in order to 
-decrease the complexity of AS design.
-
-To grant permission for an application service to masquerade as a user:
-
-Inputs:
- - Credentials of user (e.g. ``access_token``)
- - The user ID within an application service's namespace to claim.
- - Restrictions if any (e.g. only for rooms X,Y,Z. Only for 10 hours. etc)
-Output:
- - None.
-Side effects:
- - The home server will generate an ``access_token`` and push it to the 
-   application service along with both user IDs if this response 200s.
-Notes:
- - Repeated calls to this API should invalidate any existing token for this
-   user ID / application service combo and provision a new token which is then
-   pushed.
- - The generated access token MUST honour the restrictions laid out by the 
-   client.
-   
-::
-
- PUT /appservices/$virtual_user_id?access_token=$token
- 
- Request format
- {
-   restrictions: {
-     expires_in: 3600,
-     rooms: [
-      "!fl3rwfehw:matrix.org",
-      "!fwet2yugs:matrix.org"
-     ]
-   }
- }
-
-To revoke permission for an application service to masquerade as a user:
-
-Inputs:
- - Credentials of user (e.g. ``access_token``)
- - The user ID within an application service's namespace to revoke. If blank,
-   revokes all virtual user IDs linked to this matrix user ID.
-Output:
- - None.
-Side effects:
- - The home server invalidate all access tokens for this user ID / AS combo
-   and push this invalidation to the application service if this response 200s.
-   
-::
-
- DELETE /appservices/$virtual_user_id?access_token=$token
-
-
 Client-Server v2 API Extensions
 -------------------------------
 
 Identity assertion
 ~~~~~~~~~~~~~~~~~~
-The client-server API infers the user ID from the ``access_token`` provided in every
+The client-server API infers the user ID from the ``access_token`` provided in 
-request. It would be an annoying amount of book-keeping to maintain tokens for every
+every request. It would be an annoying amount of book-keeping to maintain tokens
-virtual user. It would be preferable if the application service could use the CS API
+for every virtual user. It would be preferable if the application service could
-with its own ``as_token`` instead, and specify the virtual user they wish to be 
+use the CS API with its own ``as_token`` instead, and specify the virtual user
-acting on behalf of. For real users, this would require additional permissions (see
+they wish to be acting on behalf of. For real users, this would require 
-"C-AS Linking").
+additional permissions (see "C-AS Linking").
 
 Inputs:
  - Application service token (``access_token``)
@@ -243,9 +222,9 @@ Inputs:
    - OAuth2 token of real user (which may end up being an access token) 
 Notes:
  - This will apply on all aspects of the CS API, except for Account Management.
- - The ``as_token`` is inserted into ``access_token`` which is usually where the client
+ - The ``as_token`` is inserted into ``access_token`` which is usually where the
-   token is. This is done on purpose to allow application services to reuse client
+   client token is. This is done on purpose to allow application services to 
-   SDKs.
+   reuse client SDKs.
 
 ::
 
@@ -288,3 +267,15 @@ namespace, both for users and for room aliases. This means that the AS should
 be able to create/edit/delete any room alias in its namespace, as well as
 create/delete any user in its namespace. This does not require any additional
 public APIs.
+
+
+ID conventions
+--------------
+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.
+
+- What do user IDs look like? Butchered URIs? Can all 3P network IDs be
+  reasonably expressed as URIs? (e.g. tel, email, irc, xmpp, ...)
+- What do room aliases look like? Some cases are clear (e.g. IRC) but others
+  are a lot more fiddly (e.g. email? You don't want to share a room with
+  everyone who has ever sent an email to ``bob@gmail.com``)...