Data As PNG - send files via MMS

Introduction

This project provides a RESTful message queue with extended functionality for asynchronous machine-to-machine (nowadays called IoT, Internet of Things) communication. This queue can be used for passing simple messages from embedded systems up to inter-node communication for distributed applications.

There is no limitation on message count, frequency, size .. except the server's capabilities and its limits (well, Google makes me increasingly unhappy, but as this can also be run standalone, they are not that much limitation).

Theory First

In general, we have four types of messages which can be sent through node0 api:

  1. REGULAR - a simple one-way message; send a message on specified topic and do not expect reply. This message is removed from the queue when being picked up by a topic listener. If timeout is set, this message will be removed from the queue even if undelivered.
  2. EXPECT_RESPONSE - queue expects to receive a response within specified timeframe. Timeout resets message status from SENT to NEW after specified timeout so it can be re-delivered to another node.
  3. RESPONSE - a response on a EXPECT_RESPONSE message. Upon its arrival to node0 server a corresponding EXPECT_RESPONSE message is removed. No timeout is applied, this message can remain on server for eternity.
  4. BROADCAST - a message with high priority, which is being sent to all topic readers until its expiration.

As already mentioned, messages can be in NEW and SENT states, while the latter is valid only for EXPECT_RESPONSE message type.

Messages are being sent through simple GET or POST requests. All parameters are simple strings or integers. When creating a new adapter/api, it is a good habit to base64 the message body before submitting. Larger messages is better to send using a POST request.

Responses (upon GET/POST request) are plain texts on multiple lines (separated by '\n') with fixed structure. Details below.

Show Me Some Meat!

If you are not interested in node0 API 'internals', you can directly skip to APIs. Click here to see Python or Java API.

All operations are minimalisticaly simple and clear. In the following example you can also replace replace localhost:8080 by node0.appspot.com to see instantly what happens! :)

Sending a Message

Imagine you want to send a simple "Hello world!" message on topic 'myTopic' with expiration time set to 123 seconds.

The only 'tough' thing here is that you need to make the message body url-friendly as it contains a space character.

For example in Python, it is as simple as this:

>>> import base64
>>> print base64.urlsafe_b64encode("Hello world!")
SGVsbG8gd29ybGQh

Then, the only thing you do is to issue such GET request:

http://localhost:8080/sendMessage?topic=myTopic&message=SGVsbG8gd29ybGQh&msgType=REGULAR&timeout=123

In response you receive just 1 or 0 indicating that message has or has not been accepted.

Reading a Message

Reading a message is even easier, you just call

http://localhost:8080/readMessage?topic=myTopic

which returns you plain text delimited by '\n' character with the following lines:

1
agxkZXZ-bm9kZW51bGFyIQsSB01lc3NhZ2UiB215VG9waWMMCxIHTWVzc2FnZRgFDA
SGVsbG8gd29ybGQh

where first line contains number of messages in the output, second line is a message key (used when sending a RESPONSE message), and finally on the third line also the actual message. In case there are no new messages, 0 on the first line is returned, indicating there are no messages available.

Sending a Response

When sending a RESPONSE message there is one more parameter that needs to be sent with the message. The parameter is msgKey, containing the message key received together with last read message. Also the msgType must be set to RESPONSE so the server can link this response to corresponding message (originally issued with type EXPECT_RESPONSE).

http://localhost:8080/sendMessage?topic=myTopic&message={based response message}&msgType=RESPONSE&msgKey={last received key}

The response is same as when sending a REGULAR message.

Please note, that when sending a RESPONSE message with key which originally belonged to REGULAR message, incoming message is simply ignored and not stored in the queue.

Listing All Responses

There is also possiblity to list all responses or even messages:

http://localhost:8080/listMessages?topic=myTopic&msgType=RESPONSE&page=0

First line contains number of messages. Then, msgKey-message pairs follow.

5
agxkZXZ-bm9kZW51bGFyIQsSB01lc3NhZ2UiB215VG9waWMMCxIHTWVzc2FnZRgFDA
SGVsbG8gd29ybGQh
....

The page parameter starts with 0 and can be increased until the first line in response is greater than 0 (until there are messages to be listed). Listing the messages does not remove messages from the queue. Only readMessage does.

There is a limit on max number of messages to be on one page (currently set to 100 or 200). This value needs to be reduced if messages are too big (the request time outs) or increased in case there are many little messages (limited 'database small ops').

Raw node0 API Overview

This is a thorough overview of the node0 API functionality. All parameters are mandatory, optional marked with *.

ActionParameterDescriptionResponse
sendMessagetopicwhich topic (imagine a 'mail box') is this message send to0/1
(=False/True) - messages has (not) been accepted
messagebase64d message body
msgType*message type ∈ {REGULAR, EXPECT_RESPONSE (default), RESPONSE, BROADCAST}
timeout*seconds after a message is deleted or set as available for re-delivery (msgType=EXPECT_RESPONSE). When not set, the message will never be deleted. By default set to -1 = no timeout.
msgKey*message key to identify to which message is this one a RESPONSE. Used only when responding on EXPECT_RESPONSE message.
readMessagetopictopic of a message to read. The message can be one of the above mentioned message types. Messages are ordered as they were sent (FIFO), higher priority message (BROADCAST) are being sent until timeouted.0/1
(=no message/one message)
messageKey
message
msgTypemessage type you intend to read
listMessagestopictopic, whose messages will be listednumMessages
messageKey#1
message#1
messageKey#2
message#2
....
messageKey#numMessages
message#2#numMessages
msgTypeone of the message types
page starting by zero, stop iterating when first line in response (numMessages) equals to zero.
dropTopictopictopic to be dropped. All messages are deleted.numDroppedMessages

Additional node0 API Functions

The following API functions are not strictly related to node0 functionality but may be of use or convenience when using node0 messages.

ActionParameterDescriptionResponse
getCurrentUTCTimestampcurrent UTC unix timestamp in seconds; useful for simple connected/iot devices to obtain date/time informationUTC timestamp

Python API

Using a higher-level API will certainly ease some tasks for you. All the examples are available in the download section.

Sending a Message

It is so simple. You don't even need to specify the msgType and timeout (msgType=REGULAR and no timeout are by default).

Reading a Message

Receiving a message is also very simple. "Hello world!" is printed on the last line.

Receive and Respond

Listing All Responses

Dropping Entire Topic

Java API

The source and examples are available in the download section.

Security

No security is implemented. Everyone can access any topic (when knows the 'topic' string). The topic is visible even if SSL is used - it is present in the GET request URLs.

--[[EOF]]--

Contents

Introduction
Theory First
Show Me Some Meat!
Sending a Message
Reading a Message
Sending a Response
Listing all Responses
Raw node0 API Overview
Additional node0 API Functions
Python API
Sending a Message
Reading a Message
Receive and Respond
Listing all Responses
Dropping Entire Topic
Java API
Security

Download

node0-src.zip
node0 server sources
node0api-python.bz2
node0api.py + examples
node0api-java.bz2
node0api.py + examples

Feedback

Do you like node0? Would you like to contribute, tell us you opinion or just share a brilliant idea? Use this form! :)


Last web update: 12 December 2016

Last API update: 12 December 2016

Author: Ibisek, www.ibisek.com

NAVRCHOLU.cz
pocitadlo