Subscriptions

Blot're provides a web socket based subscriptions API that allows your app to receive realtime event notifications. Subscriptions allow Blot're to push data to your app and are the preferred method of monitoring changes.

Subscriptions only provide change data. To sync the initial state of a stream, take a look at the REST or web socket response API. The response API in particular may be interesting since it allows you to make API calls over the same web socket you use for subscriptions.

Messages

Subscribe

{
    "type": "Subscribe",
    "to": [STREAM_URLS...] 
}

Subscribe to events on one or more streams. This includes StatusUpdated, ChildAdded, ChildRemoved, ParentAdded, ParentRemoved, and StreamDeleted events for the streams.

Subscriptions noop if the requested stream does not exist or if a subscription to the stream already exists. Subscriptions are not ref counted internally.

Each socket is limited to 256 active subscriptions.

Unsubscribe

{
    "type": "Unsubscribe",
    "to": [STREAM_URLS...] 
}

Unsubscribe from events on one or more streams.

Because subscriptions are not ref counted, Unsubscribe stops all updates, even if Subscribe was called multiple times for a stream.

SubscribeCollection

{
    "type": "SubscribeCollection",
    "to": STREAM_URL_OR_TAG 
}

Subscribes to child collection events on a stream. This includes the ChildAdded and ChildRemoved events for the target stream, as well as all child StatusChanged events. The stream's own StatusChange events are not part of this subscription.

Follows the same rules as Subscribe. Subscribe to a tag with to: '#TAG_NAME'.

Each socket is limited to 8 active collection subscriptions.

UnsubscribeCollection

{
    "type": "UnsubscribeCollection",
    "to": STREAM_URL_OR_TAG
}

Unsubscribes from child collection events on a stream.

Follows the same rules as Unsubscribe

Events

StatusUpdated

{
    "type": "StatusUpdate",
    "from": STREAM_URI,
    "status": STATUS,
    ?"source": SOURCE_COLLECTION_URI
}

The status of stream from has changed.

{
  "type": "StatusUpdate",
  "from": "user1/child1",
  "status": {
    "color": "#0000ff",
    "created": 1429160419760,
    "poster": "552f24f33004785713de674e"
  },
  "source": null
}

ChildAdded

{
    "type": "ChildAdded",
    "from": STREAM_URI,
    "child": ADDED_CHILD,
    ?"source": SOURCE_COLLECTION_URI
}

child was added as a child of STREAM_URI.

{
  "type": "ChildAdded",
  "from": "user1",
  "child": {
    "id": "552f5caa3004ce448e1e19a2",
    "name": "interesting_stream",
    "uri": "user2/interesting_stream",
    "created": 1429167274609,
    "updated": 1429167274609,
    "status": {
      "color": "#aaaaaa",
      "created": 1429167274609,
      "poster": "552f24f33004785713de674e"
    },
    "owner": "552f24f33004785713de674e"
  },
  "source": null
}

ParentAdded

{
    "type": "ParentAdded",
    "from": STREAM_URI,
    "parent": ADDED_PARENT_STREAM,
    ?"source": SOURCE_COLLECTION_URI
}

from was added as a child of parent. When a child is added to a stream, both a ChildAdded and ParentAdded event will be triggered.

ChildRemoved

{
    "type": "ChildAdded",
    "from": STREAM_URI,
    "child": REMOVED_CHILD_URI,
    ?"source": SOURCE_COLLECTION_URI
}

child was removed as a child of STREAM_URI.

{
  "type": "ChildRemoved",
  "from": "user1",
  "child": "user2/interesting_stream",
  "source": null
}

ParentRemoved

{
    "type": "ParentRemoved",
    "from": STREAM_URI,
    "parent": ADDED_PARENT_STREAM,
    ?"source": SOURCE_COLLECTION_URI
}

from was removed as a child of parent. When a child is removed from stream, both a ChildRemoved and ParentRemoved event will be triggered.

StreamDeleted

{
    "type": "StreamDeleted",
    "from": STREAM_URI,
    ?"source": SOURCE_COLLECTION_URI
}

Stream from has been deleted.

{
  "type": "StreamDeleted",
  "from": "user2/interesting_stream",
  "source": null
}