Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-04-27 12:54:10 +02:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

RST Formatting for github

Browse source
This commit is contained in:
Kegsay 2015-01-14 10:44:47 +00:00
parent a1aaf78186
commit 8ca0c65fd3
1 changed files with 311 additions and 288 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

109
drafts/cs-v2-http-api.rst
View file

@ -24,8 +24,13 @@ TODO: excluding filters (e.g. filter out "org.matrix.neb.*")
XXX: how do we transition between non-coalesced pagination and coalesced pagination for related_to/updates
POST /user/{userId}/filter
{
::
POST /user/{userId}/filter
.. code:: javascript
{
// selectors: (bluntly selecting on the unencrypted fields)
types: [ "m.*", "net.arasphere.*" ], // default: all
rooms: [ "!83wy7whi:matrix.org" ], // default: all (may be aliases or IDs. wildcards supported)
@ -74,7 +79,7 @@ POST /user/{userId}/filter
// N.B. we can only order by unencrypted fields.
// N.B. clients will need to handle out-of-order messages intelligently
// N.B. subset of things you're allowed to sort by may be arbitrarily
restricted by the server impl (XXX: capabilities?)
// restricted by the server impl (XXX: capabilities?)
// Servers must support the "timeline" ordering - which is linearised logical chronological ordering.
// XXX: should this be done per-request rather than per-filter? Given streaming APIs (like eventStream)
// will be limited to sorting via timeline due to causality...
@ -89,13 +94,14 @@ POST /user/{userId}/filter
dir: "asc",
},
],
}
}
Returns:
200 OK
{
"filter_id": "583e98c2d983",
}
Returns::
200 OK
{
"filter_id": "583e98c2d983"
}
Global initial sync API
@ -104,6 +110,7 @@ Global initial sync API
GET /initialSync
GET parameters::
limit: maximum number of events per room to return
sort: fieldname, direction (e.g. "sender_id,asc"). // default: "timeline,asc". may appear multiple times.
since: <chunk token> to request an incremental update (*not* pagination) since the specified chunk token
@ -122,12 +129,15 @@ GET parameters::
filter_select: event fields to return: default, all. may appear multiple times
filter_bundle_updates: true/false: default, false. bundle updates in events.
// FIXME: kegan: how much does the v1 response actually change here?
// FIXME: kegan: how much does the v1 response actually change here?
Returns:
200 OK
// where compact is false:
{
.. code:: javascript
200 OK
// where compact is false:
{
"end": "s72595_4483_1934", // the chunk token we pass to from=
// global presence info (if presence=true)
@ -188,11 +198,11 @@ Returns:
}],
"visibility": "public"
}]
}
}
// where compact is true:
{
// where compact is true:
{
"end": "s72595_4483_1934",
// global presence info
"presence": [{
@ -235,13 +245,14 @@ Returns:
"state": [ "$1417731086506PgoVf:matrix.org" ],
"visibility": "public"
}]
}
}
Event Stream API
----------------
GET /eventStream
GET parameters::
from: chunk token to continue streaming from (e.g. "end" given by initialsync)
filter*: as per initialSync (XXX: do we inherit this from the chunk token?)
// N.B. there is no limit or sort param here, as we get events in timeline order as fast as they come.
@ -249,14 +260,16 @@ GET parameters::
timeout: maximum time to poll before returning the request
presence: "offline" // optional parameter to tell the server not to interpret this as coming online
XXX: this needs to be updated from v1. Presumably s/user_id/sender_id/?
XXX: this needs to be updated from v1. Presumably s/user_id/sender_id/?
Returns:
200 OK
// events precisely as per a room's eventStream key as returned by initialSync
// includes non-graph events like presence
{
.. code:: javascript
// events precisely as per a room's eventStream key as returned by initialSync
// includes non-graph events like presence
{
"chunk": [{
"content": {
"avatar_url": "https://matrix.org/_matrix/content/QG1hdHRoZXc6bWF0cml4Lm9yZwxaesQWnqdynuXIYaRisFnZdG.aW1hZ2UvanBlZw==.jpeg",
@ -280,7 +293,7 @@ Returns:
}],
"end": "s75460_2478_981",
"start": "s75459_2477_981" // XXX: do we need start here?
}
}
Room Creation API
-----------------
@ -296,14 +309,17 @@ Scrollback API
GET /rooms/<room_id>/events
GET parameters::
from: the chunk token to paginate from
Otherwise same as initialSync, except "compact", "since" and "presence" are not implemented
Returns:
200 OK
// events precisely as per a room's eventStream key as returned by initialSync
{
.. code:: javascript
// events precisely as per a room's eventStream key as returned by initialSync
{
"chunk": [{
"age": 28153452, // XXX: age and origin_server_ts are redundant here surely
"content": {
@ -329,22 +345,25 @@ Returns:
}],
"end": "t9571-74545_2470_979",
"start": "t9601-75400_2470_979" // XXX: don't we just need end here as we can only paginate one way?
}
}
Contextual windowing API
~~~~~~~~~~~~~~~~~~~~~~~~
GET /events/<event_id>
GET parameters:
GET parameters::
context: "before", "after" or "around"
Otherwise same as initialSync, except "since" and "presence" are not implemented
Returns:
200 OK
// the room in question, formatted exactly as a room entry returned by /initialSync
// with the event in question present in the list as determined by the context param
{
.. code:: javascript
// the room in question, formatted exactly as a room entry returned by /initialSync
// with the event in question present in the list as determined by the context param
{
"events": {
"$1417731086506PgoVf:matrix.org": {
"content": {
@ -373,7 +392,7 @@ Returns:
"room_id": "!KrLWMLDnZAyTapqLWW:matrix.org",
"state": [ "$1417731086506PgoVf:matrix.org" ],
"visibility": "public"
}
}
Room Alias API
@ -389,10 +408,12 @@ Provides arbitrary per-user global state JSON storage with namespaced keys,
some of which have specific predefined serverside semantics. Keys must be named
(we don't support POSTing to anonymous key names)
PUT /user/{userId}/data/m.displayname
PUT /user/{userId}/data/m.avatar_url
PUT /user/{userId}/data/m.contact_vcard
PUT /user/{userId}/data/net.arasphere.client.preferences
::
PUT /user/{userId}/data/m.displayname
PUT /user/{userId}/data/m.avatar_url
PUT /user/{userId}/data/m.contact_vcard
PUT /user/{userId}/data/net.arasphere.client.preferences
Account Management API
----------------------
@ -403,17 +424,19 @@ Actions API
Presence API
------------
PUT /user/{userId}/presence/m.status // set DND/asleep/on holiday etc -
// XXX: do we need to distinguish between internationalisable presets like DND
// and free-form textual status messages?
// XXX: should this be in /user/{userId}/data/m.status instead?
// what's actually the difference? surely status is no different to avatar
// updates in terms of needing to be pushed around
::
PUT /device/{deviceId}/presence/m.presence // explicitly set online/idle/offline
// or /presence/device/{deviceId}
PUT /user/{userId}/presence/m.status // set DND/asleep/on holiday etc -
// XXX: do we need to distinguish between internationalisable presets like DND
// and free-form textual status messages?
// XXX: should this be in /user/{userId}/data/m.status instead?
// what's actually the difference? surely status is no different to avatar
// updates in terms of needing to be pushed around
// XXX: need to remember how to handle activity notifications
PUT /device/{deviceId}/presence/m.presence // explicitly set online/idle/offline
// or /presence/device/{deviceId}
// XXX: need to remember how to handle activity notifications
Typing API
----------