Streams

Want to make your project talk to the Internet? Connect your existing project to the Internet to log, stream, and interact with the data it produces? What about all this Internet of Things (IoT) stuff?

Streams is a platform we're designing to display, respond, and interact with your project's data.

We couldn't find a good way to interact with them over the Internet. There are certainly a lot of great services out there for datalogging, or communicating with your microcontroller over the web, but these services are either too complicated to get started, or they aren't particularly fun to use. So, we decided to experiment with our own system, and that's Streams.

Active Streams

{{streamsVm.formatConnectedState()}}
Stream Data Timestamp
{{item.stream}} {{item.data}}
No streams found.

HTTP API Overview

The HTTP API is simple, we have one end point for publishing and two end points for interrogation and retrieval.

POST/meta/streams Add a new data point.

Overview

Adds data points to a stream.

Parameters

Adding data points consist of two required attributes and three optional.

Name Required Description
stream Y Name of the stream. Max length of 32 characters from [0-9a-zA-Z].
data Y Arbitrary data to be stored.
origin N Name of the origin. Defaults to '-'.
type N The type of data point. For example 'temperature', 'humidity'. Defaults to '-'.
lifetime N Lifetime of the data point in seconds. Defaults to 2,678,400 seconds (31 days).

Return

A successful return has a HTTP status code of 200 and a JSON body containing a message and a timestamp of the server UTC time.

An unsuccessful return has a HTTP status code of 400 and a JSON body containing a message of the error and a timestamp of the server UTC time.

Examples

$ curl -H "Content-Type: application/json" -d '{"stream":"foo","data":{"bar":"baz"}}' https://ballarathackerspace.org.au/meta/streams
{"status":"ok","ts":1534465584}
$ curl -H "Content-Type: application/json" -d '{"stream":"@#$#", "data":{"foo":"bar"}}' https://ballarathackerspace.org.au/meta/streams
{"error":"Stream name is missing/invalid.","ts":1534490021}
GET/meta/streams.json List available streams.

Overview

Retrieves a paginated list of all the available streams.

Parameters

There are no required attributes for listing data streams, and two optional ones for pagination.

Name Required Description
relative N A relative offset for the next page of results.

Return

A successful return has a HTTP status code of 200 and a JSON body containing an paginated object of the available stream names and a timestamp of the server UTC time.

An unsuccessful return has a HTTP status code of 400 and a JSON body containing a message of the error and a timestamp of the server UTC time.

Examples

curl -H "Content-Type: application/json" https://ballarathackerspace.org.au/meta/streams.json
{"streams":{"items":[{"points":13,"stream":"bar","timestamp":1537191646},{"points":12,"stream":"foo","timestamp":1537189715},{"points":6,"stream":"baz","timestamp":1536723035}],"relative":"1536723035.665"},"ts":1537192316}
GET/meta/streams/:stream.json List data points from the specified :stream.

Overview

Retreives a paginated list of a stream's available data points.

Parameters

There are no required attributes for listing data streams, and two optional ones for pagination.

Name Required Description
relative N A relative offset for the next page of results.

Return

A successful return has a HTTP status code of 200 and a JSON body containing a paginated object of the available data points message and a timestamp of the server UTC time.

An unsuccessful return has a HTTP status code of 400 and a JSON body containing a message of the error and a timestamp of the server UTC time.

Examples

$ curl -H "Content-Type: application/json" https://ballarathackerspace.org.au/meta/stream/foo.json
{"items":[{"data":{"bar":"202"},"stream":"foo","timestamp":1537189715,"type":""},{"data":{"bar":"6134"},"stream":"foo","timestamp":1537180954,"type":""},{"data":{"bar":"26663"},"stream":"foo","timestamp":1537180935,"type":""},{"data":{"bar":"29019"},"stream":"foo","timestamp":1536723018,"type":""},{"data":{"foo":"25263"},"stream":"foo","timestamp":1536723003,"type":""},{"data":{"foo":"24072"},"stream":"foo","timestamp":1536722999,"type":""},{"data":{"foo":"17415"},"stream":"foo","timestamp":1536722998,"type":""},{"data":{"foo":"3582"},"stream":"foo","timestamp":1536722997,"type":""},{"data":{"foo":"524"},"stream":"foo","timestamp":1536722978,"type":""},{"data":{"foo":"18465"},"stream":"foo","timestamp":1536722977,"type":""}],"relative":"1536722977.653"}
$ curl -H "Content-Type: application/json" https://ballarathackerspace.org.au/meta/stream/foo.json?fetch=2
{"items":[{"data":{"bar":"202"},"stream":"foo","timestamp":1537189715,"type":""},{"data":{"bar":"6134"},"stream":"foo","timestamp":1537180954,"type":""}],"relative":"1537180954.667"}
$ curl -H "Content-Type: application/json" https://ballarathackerspace.org.au/meta/stream/foo.json?fetch=2&relative=1537180954.667
{"items":[{"data":{"bar":"26663"},"stream":"foo","timestamp":1537180935,"type":""},{"data":{"bar":"29019"},"stream":"foo","timestamp":1536723018,"type":""}],"relative":"1536723018.659"}

MQTT Overview

An MQTT bridge is also available on port 1883 and requires the streams/ prefix to your stream name.