From 34b6ab6ec25264884cfe2ed4435ab3cc4a8d658e Mon Sep 17 00:00:00 2001 From: Jeremy Lakeman Date: Tue, 30 May 2017 09:27:48 +0930 Subject: [PATCH] Update restful api docs --- doc/REST-API-MeshMB.md | 78 +++++++++++++++++++++++++++++++++++++++++ doc/REST-API-MeshMS.md | 44 +++++++++++++++++------ doc/REST-API-Rhizome.md | 21 +++++++++-- doc/REST-API.md | 38 ++++++++++++++++---- 4 files changed, 161 insertions(+), 20 deletions(-) create mode 100644 doc/REST-API-MeshMB.md diff --git a/doc/REST-API-MeshMB.md b/doc/REST-API-MeshMB.md new file mode 100644 index 00000000..4c22060b --- /dev/null +++ b/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 diff --git a/doc/REST-API-MeshMS.md b/doc/REST-API-MeshMS.md index d6b8fab3..7df1119a 100644 --- a/doc/REST-API-MeshMS.md +++ b/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.** diff --git a/doc/REST-API-Rhizome.md b/doc/REST-API-Rhizome.md index a86a0f64..d5ad60c0 100644 --- a/doc/REST-API-Rhizome.md +++ b/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.** diff --git a/doc/REST-API.md b/doc/REST-API.md index 3e14e1f7..8821e56a 100644 --- a/doc/REST-API.md +++ b/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