RST Formatting for github

This commit is contained in:
Kegsay 2015-01-14 10:44:47 +00:00
parent a1aaf78186
commit 8ca0c65fd3

View file

@ -24,7 +24,12 @@ 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 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) // selectors: (bluntly selecting on the unencrypted fields)
types: [ "m.*", "net.arasphere.*" ], // default: all types: [ "m.*", "net.arasphere.*" ], // default: all
@ -74,7 +79,7 @@ POST /user/{userId}/filter
// N.B. we can only order by unencrypted fields. // N.B. we can only order by unencrypted fields.
// N.B. clients will need to handle out-of-order messages intelligently // 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 // 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. // 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) // 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... // will be limited to sorting via timeline due to causality...
@ -91,10 +96,11 @@ POST /user/{userId}/filter
], ],
} }
Returns: Returns::
200 OK 200 OK
{ {
"filter_id": "583e98c2d983", "filter_id": "583e98c2d983"
} }
@ -104,6 +110,7 @@ Global initial sync API
GET /initialSync GET /initialSync
GET parameters:: GET parameters::
limit: maximum number of events per room to return limit: maximum number of events per room to return
sort: fieldname, direction (e.g. "sender_id,asc"). // default: "timeline,asc". may appear multiple times. 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 since: <chunk token> to request an incremental update (*not* pagination) since the specified chunk token
@ -125,6 +132,9 @@ GET parameters::
// FIXME: kegan: how much does the v1 response actually change here? // FIXME: kegan: how much does the v1 response actually change here?
Returns: Returns:
.. code:: javascript
200 OK 200 OK
// where compact is false: // where compact is false:
{ {
@ -242,6 +252,7 @@ Event Stream API
GET /eventStream GET /eventStream
GET parameters:: GET parameters::
from: chunk token to continue streaming from (e.g. "end" given by initialsync) 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?) 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. // N.B. there is no limit or sort param here, as we get events in timeline order as fast as they come.
@ -254,6 +265,8 @@ XXX: this needs to be updated from v1. Presumably s/user_id/sender_id/?
Returns: Returns:
200 OK 200 OK
.. code:: javascript
// events precisely as per a room's eventStream key as returned by initialSync // events precisely as per a room's eventStream key as returned by initialSync
// includes non-graph events like presence // includes non-graph events like presence
{ {
@ -296,12 +309,15 @@ Scrollback API
GET /rooms/<room_id>/events GET /rooms/<room_id>/events
GET parameters:: GET parameters::
from: the chunk token to paginate from from: the chunk token to paginate from
Otherwise same as initialSync, except "compact", "since" and "presence" are not implemented Otherwise same as initialSync, except "compact", "since" and "presence" are not implemented
Returns: Returns:
200 OK 200 OK
.. code:: javascript
// events precisely as per a room's eventStream key as returned by initialSync // events precisely as per a room's eventStream key as returned by initialSync
{ {
"chunk": [{ "chunk": [{
@ -335,13 +351,16 @@ Contextual windowing API
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
GET /events/<event_id> GET /events/<event_id>
GET parameters: GET parameters::
context: "before", "after" or "around" context: "before", "after" or "around"
Otherwise same as initialSync, except "since" and "presence" are not implemented Otherwise same as initialSync, except "since" and "presence" are not implemented
Returns: Returns:
200 OK 200 OK
.. code:: javascript
// the room in question, formatted exactly as a room entry returned by /initialSync // 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 // with the event in question present in the list as determined by the context param
{ {
@ -389,6 +408,8 @@ Provides arbitrary per-user global state JSON storage with namespaced keys,
some of which have specific predefined serverside semantics. Keys must be named some of which have specific predefined serverside semantics. Keys must be named
(we don't support POSTing to anonymous key names) (we don't support POSTing to anonymous key names)
::
PUT /user/{userId}/data/m.displayname PUT /user/{userId}/data/m.displayname
PUT /user/{userId}/data/m.avatar_url PUT /user/{userId}/data/m.avatar_url
PUT /user/{userId}/data/m.contact_vcard PUT /user/{userId}/data/m.contact_vcard
@ -403,6 +424,8 @@ Actions API
Presence API Presence API
------------ ------------
::
PUT /user/{userId}/presence/m.status // set DND/asleep/on holiday etc - PUT /user/{userId}/presence/m.status // set DND/asleep/on holiday etc -
// XXX: do we need to distinguish between internationalisable presets like DND // XXX: do we need to distinguish between internationalisable presets like DND
// and free-form textual status messages? // and free-form textual status messages?