Structures

Stream

Streams are the top level structures on Blot're. Each stream has a status (color) and some metadata. Here's an example basic structure of a stream:

{
  "id": "552f68963004ce448e1e19a5",
  "name": "Vidre",
  "uri": "billyblotre/vidre",
  "created": 1429170326262,
  "updated": 1429170326262,
  "status": {
    "color": "#CC66666",
    "created": 1429170326262,
    "poster": "552f24f33004785713de674e"
  },
  "tags": ["viddy", "well"],
  "owner": "552f24f33004785713de674e"
}

• id - Short, unique identifier for the stream. Ids are usually used in the Rest API. Immutable.
• name - The name of the stream. May only contain letters, spaces, numbers, and dollar signs. Case sensitive for display purposes but case insensitive for storage (Streams "ABC" and "abc" cannot both exist on the same parent.). Immutable.
• uri - Full path to the stream. The last component of the uri is the name. Note that unlike name, uri is always lower case. The first component is usually the user who originally created the stream. Uris are usually used in the web socket APIs. Immutable.
• created - When the stream was created. Immutable.
• updated - When the stream was last updated. This includes updates to the status and tags. Not directly set using APIs.
• status - The color of the stream, the whole point.
  • status.color - The status color of the stream. Currently, colors must be provided CSS style, six hex digits prefixed with #.
  • status.created - When the current status was last set. This may be different from updated in the stream since this field only tracks status changes.
  • status.poster - Id of the user who set the status.
• tags - Array of zero or more tags that are set on the stream. See Tags for more details.
• owner - Id of the user who owns the stream.

Children

Each stream can have zero or more child streams. There are two types of child streams in Blot're: hierarchical children and added children.

Hierarchical children are streams that are direct descendants of the stream. These are what you created using the + button on a https://blot.re stream page. The uri of a hierarchical child is always: PARENT_URI + '/' + CHILD_NAME. You cannot remove hierarchical children from a parent, but the child will be removed if it is deleted.

Added children are other streams that the user has linked to a parent. These are what you created using the start button on a https://blot.re stream page. The linked child may not share any uri with its parent and may be owned by another user. Added children can be freely added and removed from a parent stream.

Tags

Tags provide detail about a stream's purpose. They will always be converted to lower case and have the same restrictions as stream names.

You can also use tags to publish a stream into a shared collection that any user can add or remove children from. These tag streams can be subscribed to just like normal streams.

{
  "id": "552f68963004ce448e1e19a5",
  "name": "Vidre",
  ...
  "tags": ["viddy", "well"]
}

When the tag "viddy" is first added to a stream, the stream is added as a child of the #viddy top level stream. Any status updates to Vidre will broadcast status change notifications over #viddy. If the tag is removed, the stream is removed as a child of #viddy.

You can then use the REST API to query the status of tag streams much like you would a normal stream. Additionally, you can subscribe to collection events on a tag stream using a web socket to be notified of StatusUpdated, ChildAdded, and ChildRemoved events. When a tag is added or removed from a stream, ParentAdded and ParentRemoved events will also be broadcast for the stream.