The Stream API provides endpoints for managing streams and stream data.

How to Start Using the API

The Stream API requires the same user account as the Handy Rest API. See API v3 for details.

If your user account can’ t issue tokens for the Stream API your account may not have the required permission. Contact us and we will add it.

Streams

A stream is a collection of movement points that can be played on a device. Each data point consist of a timestamp and a position and the points are ordered according to their timestamps.

Creating streams

Use the /streams endpoint to create a new stream. The endpoint requires an ApplicationID or client-token for authentication. When you create a stream you can specify an optional name, description and an external_ref.

The name and description should be a human readable text describing the stream. The external_ref can be some external reference. The external_ref can also be used to lookup a specific stream at a later time.

When you create a stream, the endpoint will return information about the created stream.

The import info:

• stream_id: The stream identifier, used in non public API endpoints.
• stream_ref: The stream reference. Used in public endpoints and in the Handy Rest API v3 STREAM protocol.
• data_key: Used to authenticate with the stream data endpoint.
  • Data: PUT /stream/{streamId}/data
• editor_key: Used to authenticate with the stream editor endpoints.
  • Get: GET /stream/{streamId}
  • Close PUT /stream/{streamId}/close
  • Update: PUT /stream/{streamId}
  • SSE: /stream/{streamId}/sse

It’s important to distribute stream authentication keys and stream ids/refs according to the intended use.

• Users that should be able to play the stream and listen for public stream events only needs the stream_ref
• Users that should be able to add data to the stream need the stream_id and the data_key
• Users that should be able to modify the stream properties and listen for private events need the editor_key and stream_id

Stream data

A stream works on an append only data model. This means you can only add points in the order they should be played on a device. You can not delete or insert points, only append. If you try to add points with timestamps out of order, or with a timestamp before the current last point in the stream, the data will be rejected.

Only open streams can receive data. Once a stream is closed, it’s considered finalized and no more data can be added.

Closing a stream