Update restful api docs

doc/REST-API-MeshMB.md

@@ -0,0 +1,78 @@
+MeshMB REST API
+===============
+[Serval Project][], February 2016
+
+Introduction
+------------
+
+[MeshMB][] is a service in the [Serval Mesh network][] that provides
+distributed one-to-all messaging using [Rhizome][] as transport.
+
+The [Serval DNA][] daemon that runs on every node gives applications access to
+the MeshMB service via the **MeshMB REST API** described in this document.
+
+### Basic concepts
+
+#### Feed
+
+An unencrypted rhizome journal. With the same internal format as a MeshMS message ply.
+
+Each feed has a name, set in the rhizome manifest. 
+
+The Bundle ID of the feed, is the author of the bundle. In other words, 
+the bundle secret is the same secret stored in the serval keyring to represent an identity.
+
+### POST /restful/meshmb/ID/sendmessage
+
+Append a new message to the feed.
+
+### GET /restful/meshmb/FEEDID/messagelist.json
+
+List the messages in any feed.
+
+### GET /restful/meshmb/FEEDID/newsince[/TOKEN]/messagelist.json
+
+List messages from a feed as they arrive.
+
+### GET /restful/meshmb/ID/feedlist.json
+
+List the feeds that you have subscribed to.
+
+### GET /restful/meshmb/ID/activity.json
+
+List the messages of all subscribed feeds, threaded in the order they originally arrived.
+
+### GET /restful/meshmb/ID/activity[/TOKEN]/activity.json
+
+List the messages of all subscribed feeds, as they arrive.
+
+### POST /restful/meshmb/ID/follow/FEEDID
+
+Start following this Feed.
+
+### POST /restful/meshmb/ID/ignore/FEEDID
+
+Stop following this Feed.
+
+-----
+**Copyright 2015 Serval Project Inc.**  
+![CC-BY-4.0](./cc-by-4.0.png)
+Available under the [Creative Commons Attribution 4.0 International licence][CC BY 4.0].
+
+
+[Serval Project]: http://www.servalproject.org/
+[CC BY 4.0]: ../LICENSE-DOCUMENTATION.md
+[Serval Mesh network]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:mesh_network
+[Serval DNA]: ../README.md
+[REST-API]: ./REST-API.md
+[MeshMS]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:meshms
+[Rhizome]: ./REST-API-Rhizome.md
+[200]: ./REST-API.md#200-ok
+[201]: ./REST-API.md#201-created
+[202]: ./REST-API.md#202-accepted
+[400]: ./REST-API.md#400-bad-request
+[404]: ./REST-API.md#404-not-found
+[419]: ./REST-API.md#419-authentication-timeout
+[422]: ./REST-API.md#422-unprocessable-entity
+[423]: ./REST-API.md#423-locked
+[500]: ./REST-API.md#500-server-error

doc/REST-API-MeshMS.md

@@ -13,28 +13,50 @@ the [MeshMS][] service via the **MeshMS REST API** described in this document.
 
 ### Basic concepts
 
-#### Conversation
-
-TBC
-
 #### Ply
 
-### GET /restful/meshms/RECIPIENTSID/conversationlist.json
+In rhizome, each author can only update rhizome bundles that they first created. 
+A ply is a rhizome journal bundle where each participant records their outgoing messages, 
+and any other changes to the conversation.
 
-TBC
+A ply can contain the following types of records;
+
+ * ACK - A pointer to a range of content within another ply.
+ * MESSAGE - A plain text message encoded in UTF-8.
+ * TIME - A timestamp related to the previous record.
+
+#### Conversation
+
+A MeshMS conversation consists of one or two message ply's. Each participant sets
+the sender and recipient manifest fields to the identities of the two parties in the 
+conversation.
+
+Both ply's are encrypted such that only the sender and recipient can read their contents.
+
+Whenever a new MESSAGE is detected on an incoming ply, a new ACK record is written to the
+end of the outgoing ply. This is used to indicate successful delivery, and to thread the
+display of messages in the conversation.
+
+There is no central server to assign a common ordering to messages in a conversation,
+both parties will see their outgoing messages threaded with received messages in the order
+they arrived locally. 
+
+### GET /restful/meshms/SENDERSID/conversationlist.json
+
+List all the conversations for which SENDERSID is either the sender or receiver of a ply.
+SENDERSID must be an identity in the serval keyring.
 
 ### GET /restful/meshms/SENDERSID/RECIPIENTSID/messagelist.json
 
-TBC
+List the messages in the conversation between SENDERSID and RECIPIENTSID.
 
-### GET /restful/meshms/SENDERSID/RECIPIENTSID/newsince/TOKEN/messagelist.json
+### GET /restful/meshms/SENDERSID/RECIPIENTSID/newsince[/TOKEN]/messagelist.json
 
-TBC
+List new messages in the conversation between SENDERSID and RECIPIENTSID as they arrive.
 
 ### POST /restful/meshms/SENDERSID/RECIPIENTSID/sendmessage
 
-TBC
-
+Send a new message from SENDERSID to RECIPIENTSID.
 
 -----
 **Copyright 2015 Serval Project Inc.**  

doc/REST-API-Rhizome.md

@@ -556,14 +556,14 @@ format with the following columns:
 *  `name` - the string value of the manifest's *name* field, or *null* if the
    manifest has no *name* field.
 
-### GET /restful/rhizome/newsince/TOKEN/bundlelist.json
+### GET /restful/rhizome/newsince[/TOKEN]/bundlelist.json
 
 This request allows a client to receive near-real-time notification of
 newly-arriving Rhizome bundles.
 
 Fetches a list of all bundles currently in [Serval DNA][]'s Rhizome store, in
 order of ascending insertion time, since (but not including) the bundle
-identified by TOKEN.  TOKEN must be a value taken from the non-null `.token`
+identified by TOKEN. If present, TOKEN must be a value taken from the non-null `.token`
 field of any previous *bundlelist.json* request.
 
 The list is returned in the body of the [response](#response) in [JSON table][]
@@ -933,6 +933,23 @@ The steps of the insertion logic have these variations:
 
 13. No change.
 
+### POST /restful/rhizome/import
+
+This request allows the client to store a valid manifest and payload that have been 
+obtained through some other means.
+
+*  **manifest**  A signed manifest in [text+binarysig format](#textbinarysig-manifest-format), 
+   with a correct *Content-Type* header. 
+
+*  **payload**  The content of the bundle's payload:
+   *  the form part's *Content-Type* header is currently ignored, but in future
+      it may be used to determine the default values of some manifest fields;
+   *  this parameter must occur after the *manifest* parameter, otherwise the
+      request fails with status [400 Bad Request][400] and the message ‘Missing
+      "manifest" form part’;
+   *  the *payload* parameter must not be supplied if the `filesize` field in
+      the *manifest* parameter is zero.
+
 
 -----
 **Copyright 2015 Serval Project Inc.**  

doc/REST-API.md

@@ -100,17 +100,39 @@ GET requests only accept parameters as [query parameters][] in the *path*.
 
 #### POST
 
-A **POST** request is the same as a GET request except that the first word
-of the first line is "POST", the blank line is followed by a request *body*,
-and the following request headers are mandatory:
-*   [Content-Length](#request-content-length)
-*   [Content-Type](#request-content-type)
+A **POST** request has a similar structure to a GET request except that the first word
+of the first line is "POST". 
 
 POST requests accept parameters as [query parameters][] in the *path* and also
 as a request body with a [Content-Type](#request-content-type) of
 [multipart/form-data][].  These two kinds of parameters are not exclusive; a
 request may contain a mixture of both.
 
+A POST request may also include a [Content-Length](#request-content-length)
+or [Transfer-Encoding](#request-transfer-encoding) header;
+a [Content-Type](#request-content-type); and an [Expect](#request-expect) header as described below.
+
+#### Request Transfer-Encoding
+
+In a request, a **Transfer-Encoding** header of "chunked", indicates that the
+client can generate and transmit the request body without pre-calculating the
+final length. No other transfer encodings are currently supported.
+
+Each chunk is generated as the size of the chunk in hex, followed
+by '\r\n', followed by the request bytes, followed by another '\r\n'.
+
+The end of the input is indicated with a chunk of zero length.
+
+#### Request Expect
+
+The presense of an **Expect** header of "100-Continue" indicates that the server 
+should respond with an intermediate response of "HTTP/1.1 100 Continue" before the
+client begins to transmit a request body. 
+
+If for any reason the server determines that the request body is not needed, or
+the request is invalid, the server will generate the response immediately without 
+reading the contents of the request body.
+
 #### Request Content-Length
 
 In a request, the **Content-Length** header gives the exact number of bytes
@@ -120,6 +142,8 @@ is too large, the request will suspend and eventually time out.  Serval DNA
 will ignore any bytes received after it has read Content-Length bytes, so if
 Content-Length is too small, the request body will be malformed.
 
+A missing Content-Length header will be treated the same as a Content-Length of zero.
+
 #### Request Content-Type
 
 In a request, the **Content-Type** header gives the [Internet Media Type][] of
@@ -297,8 +321,8 @@ path that only supports [POST](#post), or vice versa.
 
 #### 411 Length Required
 
-A `POST` request did not supply a [Content-Length](#request-content-length)
-header.
+A `POST` request did not supply either a [Content-Length](#request-content-length)
+or [Transfer-Encoding](#request-transfer-encoding) header.
 
 #### 414 Request-URI Too Long