archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add room query API. Remove linking API.

Browse Source 
Also add section on ID conventions which need thinking about.
pull/977/head
Kegsay 10 years ago
parent f33b722e4b
commit 1d45dc08ca
1 changed files with 81 additions and 90 deletions
Show Stats Download Patch File Download Diff File

171
drafts/as-http-api.rst
Unescape Escape View File

@ -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,96 +135,71 @@ 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
Service's namespace.
Pushing ``[TODO]``
~~~~~~~~~~~~~~~~~~
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:
This API is called by the HS to query the existence of a room alias on the
Application Service's namespace.
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)
- Room alias
- HS Credentials
Output:
- None.
- The current state events for the room if any.
- The message events for the room if any.
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.
- 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:
- 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.
- 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.
::
PUT /appservices/$virtual_user_id?access_token=$token
GET /rooms/$room_alias?access_token=$hs_token
Request format
{
restrictions: {
expires_in: 3600,
rooms: [
"!fl3rwfehw:matrix.org",
"!fwet2yugs:matrix.org"
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
},
...
]
}
}
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.
::
Pushing ``[TODO]``
~~~~~~~~~~~~~~~~~~
This API is called by the HS when the HS wants to push an event (or batch of
events) to the AS.
DELETE /appservices/$virtual_user_id?access_token=$token
- Retry semantics
- Ordering
Client-Server v2 API Extensions
@ -228,12 +207,12 @@ Client-Server v2 API Extensions
Identity assertion
~~~~~~~~~~~~~~~~~~
The client-server API infers the user ID from the ``access_token`` provided in every
request. It would be an annoying amount of book-keeping to maintain tokens for every
virtual user. It would be preferable if the application service could use the CS API
with its own ``as_token`` instead, and specify the virtual user they wish to be
acting on behalf of. For real users, this would require additional permissions (see
"C-AS Linking").
The client-server API infers the user ID from the ``access_token`` provided in
every request. It would be an annoying amount of book-keeping to maintain tokens
for every virtual user. It would be preferable if the application service could
use the CS API with its own ``as_token`` instead, and specify the virtual user
they wish to be acting on behalf of. For real users, this would require
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
token is. This is done on purpose to allow application services to reuse client
SDKs.
- The ``as_token`` is inserted into ``access_token`` which is usually where the
client token is. This is done on purpose to allow application services to
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``)...
Write Preview
Loading…
Cancel
Save