RST Formatting for github

drafts/cs-v2-http-api.rst

@@ -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:
+Returns::
-200 OK
+
-{
+    200 OK
-    "filter_id": "583e98c2d983",
+    {
-}
+        "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
+.. code:: javascript
-// includes non-graph events like presence
+
-{
+    // 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
+.. code:: javascript
-// with the event in question present in the list as determined by the context param
+
-{
+    // 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/m.displayname
-PUT /user/{userId}/data/net.arasphere.client.preferences
+    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
+    PUT /user/{userId}/presence/m.status // set DND/asleep/on holiday etc -
-// or /presence/device/{deviceId}
+    // 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
 ----------