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 also keep your data private (data feeds are private by default) and secure (we will never sell or give this data away to another company) for you.
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.
The HTTP API is simple, we have one end point for publishing and two end points for interrogation and retrieval.
/meta/streams
Add a new data point.
Adds data points to a stream.
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 | A string of arbitrary data to be stored. |
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.
$ 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}
/meta/streams.json
List available streams.
Retrieves a paginated list of all the available streams.
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. |
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.
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}
/meta/streams/:stream.json
List data points from the specified :stream
.
Retreives a paginated list of a stream's available data points.
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. |
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.
$ curl -H "Content-Type: application/json" https://ballarathackerspace.org.au/meta/streams/foo.json
{"items":[{"data":{"bar":"202"},"stream":"foo","timestamp":1537189715},{"data":{"bar":"6134"},"stream":"foo","timestamp":1537180954},{"data":{"bar":"26663"},"stream":"foo","timestamp":1537180935},{"data":{"bar":"29019"},"stream":"foo","timestamp":1536723018},{"data":{"foo":"25263"},"stream":"foo","timestamp":1536723003},{"data":{"foo":"24072"},"stream":"foo","timestamp":1536722999},{"data":{"foo":"17415"},"stream":"foo","timestamp":1536722998},{"data":{"foo":"3582"},"stream":"foo","timestamp":1536722997},{"data":{"foo":"524"},"stream":"foo","timestamp":1536722978},{"data":{"foo":"18465"},"stream":"foo","timestamp":1536722977}],"relative":"1536722977.653"}
$ curl -H "Content-Type: application/json" https://ballarathackerspace.org.au/meta/streams/foo.json?fetch=2
{"items":[{"data":{"bar":"202"},"stream":"foo","timestamp":1537189715},{"data":{"bar":"6134"},"stream":"foo","timestamp":1537180954}],"relative":"1537180954.667"}
$ curl -H "Content-Type: application/json" https://ballarathackerspace.org.au/meta/streams/foo.json?fetch=2&relative=1537180954.667
{"items":[{"data":{"bar":"26663"},"stream":"foo","timestamp":1537180935},{"data":{"bar":"29019"},"stream":"foo","timestamp":1536723018}],"relative":"1536723018.659"}
An MQTT bridge is also available on port 1883 and requires the streams/
prefix to your stream name.