mirror of
https://github.com/servalproject/serval-dna.git
synced 2024-12-21 14:07:53 +00:00
89 lines
3.1 KiB
Markdown
89 lines
3.1 KiB
Markdown
MeshMS REST API
|
|
===============
|
|
[Serval Project][], February 2016
|
|
|
|
Introduction
|
|
------------
|
|
|
|
[MeshMS][] is a service in the [Serval Mesh network][] that provides secure,
|
|
distributed one-to-one messaging using [Rhizome][] as transport.
|
|
|
|
The [Serval DNA][] daemon that runs on every node gives applications access to
|
|
the [MeshMS][] service via the **MeshMS REST API** described in this document.
|
|
|
|
Basic concepts
|
|
--------------
|
|
|
|
#### Ply
|
|
|
|
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.
|
|
|
|
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 [plys](#ply). 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.
|
|
|
|
MeshMS REST API operations
|
|
--------------------------
|
|
|
|
### 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
|
|
|
|
List the messages in the conversation between SENDERSID and RECIPIENTSID.
|
|
|
|
### GET /restful/meshms/SENDERSID/RECIPIENTSID/newsince[/TOKEN]/messagelist.json
|
|
|
|
List new messages in the conversation between SENDERSID and RECIPIENTSID as they arrive.
|
|
|
|
### POST /restful/meshms/SENDERSID/RECIPIENTSID/sendmessage
|
|
|
|
Send a new message from SENDERSID to RECIPIENTSID.
|
|
|
|
-----
|
|
**Copyright 2015 Serval Project Inc.**
|
|
**Copyright 2016 Flinders University**
|
|
|
|
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
|