Messages

Documents with a #messages key at the first level are inbox documents, and accept messages:

Messages are sent using the write token of the document. For that purpose, the write token of an inbox document is shared with all potential senders. The read token is kept secret by the owner.

Messages are small JSON documents of up to 4096 bytes. They may contain some data, or refer to other documents or blobs.

Every message has an 16-hexdigit message ID, which is randomly generated by the sender. Messages can be updated by sending a message with the same ID, and a newer revision field ("#": ...). The revision is usually a Unix timestamp in milliseconds since epoch. If no revision field is present, the revision is assumed to be 0.

The owner can use an inbox document like any other document. To read the messages, it loads the document, and typically removes all processed messages from the list.

JavaScript

Using Backend.js, a message can be sent as follows:

const backend = new Backend('https://viereck.ch/backend');

const writeToken = '1b599fd0...';
const messageId = backend.randomMessageId();
const message = {
	'#': new Date().getTime(),
	type: 'temperature',
	value: 21.1
	};
backend.sendMessage(writeToken, messageId, message, onDone, onError);

function onDone(request) {
	...
}

function onError(errorCode, request) {
	...
}
		

HTTP/REST Requests

Send a message

POST /backend/documents/WRITETOKEN/messages/ID

JSON MESSAGE

Adds or merges a message on an inbox document. The message ID must be a 16-hexdigit token.

Delete a message

DELETE /backend/documents/WRITETOKEN/messages/ID

Removes a message.

Message removal should be used with care. First of all, the message may already have been read by the recipient. Second, message removal is not a forward operation: after the removal, an old version of the message may get merged — either by a valid request, a concurrent request, or a (malicious) replay of a previous request.

Nevertheless message removal is useful and safe when used properly.

UDP Requests

If UDP is enabled, the following requests are available.

Send a message

Adds or merges a message on an inbox document, and responds with an "M" message upon success.

If the document is not an inbox, "N" is returned.

Delete a message

Removes a message. See above for a discussion about message removal.