Web Socket Response API

The web socket send/receive API is roughly the equivalent of the REST API, but over a web socket. Each client message will produce a single response message. Some operations require user authorization.

For realtime event notifications, see the web socket based subscription API. The subscription and the response APIs can operate over the same socket.

Stream Operations

Basic Operations
Status
- Get Status
- Set Status
Children
Tags
- Get Tags
- Set Tags
- Get Tag
- Set Tag
- Delete Tag

Basics

Responses

Each request sent over the socket will produce one response message (unless there is an internal server error). The order in which requests are sent may not match the order in which their responses are received.

A response may return requested data or report that an error occurred.

Correlation

We recommend that you design your application to be agnostic about message ordering. But sometimes it helps to know which request produced which received response. This is especially true for error messages.

Blot're allows you to attach a unique id to requests so that the requests can be correlated with responses. If the correlation id is provided, the response message sent back to your application, error or success, will have the same correlation value.

SEND { "type": "GetStatus", "of": "non/existent/stream", "correlation": 42 }

RECEIVE { "type": "Error", "error": "No such stream.", "correlation": 42 }

The correlation id can be any integer value. Blot're provides zero logic for correlation, your client is fully responsible for generating and understanding the meaning of this the correlation id. Correlation also is not required.

Disabling Success Ack

You can disable the success acknowledgment for a message by setting the acknowledge field to 'error'. Two options are supported:

Default - Ack successes and send error messages.
'error' - Only send error responses, do not send success Acks. This is preferred if you sending multiple updates per second that do not depend on response data.

Stream Operations

`GetStream`

{
    "type": "GetStream",
    "uri": STREAM_URL
}

Lookup a stream by uri.

Example

SEND {
  "type": "GetStream",
  "uri": "user1/stream1"
}

RESPONSE {
  "type": "Stream",
  "correlation": 0,
  "id": "553d7e6f30043b38ce3f7050",
  "name": "stream1",
  "uri": "user1/stream1",
  "created": 1430093423080,
  "updated": 1430456148918,
  "status": {
    "color": "#333333",
    "created": 1430456148918,
    "poster": "553d7e6b30043b38ce3f704e"
  },
  "owner": "553d7e6b30043b38ce3f704e"
}

Errors

Stream does not exist.

GetStreams

Get multiple streams. The default behavior is to return most recently updated streams. An optional query parameters can be used to search strings by name, status, or tag.

Example

SEND {
  "type": "GetStreams",
  ?"query": "toast"
}

RESPONSE {
  "type": "Streams",
  "streams": {
    "id": "552f68963004ce448e1e19a5",
    "name": "ToasterPrime",
    "uri": "toastmastergeneral/toasterprime",
    "created": 1429170326262,
    "updated": 1429170326262,
    "status": {
      "color": "#0000ff",
      "created": 1429170326262,
      "poster": "552f24f33004785713de674e"
    },
    "tags": [{"tag": "toaster"}, {"tag": "energoncubebreakfast"}],
    "owner": "552f24f33004785713de674e"
  }, {
    "id": "5550fcc9300496217de54ebf",
    "name": "Deceptitoast",
    "uri": "sirbakealot/deceptitoast",
    "created": 1429170326262,
    "updated": 1429170326262,
    "status": {
      "color": "#000000",
      "created": 1429170326262,
      "poster": "5550f2a63004a531be8820c5"
    },
    "tags": [{"tag": "thetoastisalie"}, {"tag": "energoncubebreakfast"}],
    "owner": "5550f2a63004a531be8820c5"
  }]
}

`CreateStream`

{
  "type": "CreateStream",
  "name": NEW_STREAM_NAME,
  "uri": NEW_STREAM_URI,
  ?"status": STATUS
}

Creates a new stream with optional status. Same restrictions as with the REST API apply.

Example

SEND {
  "type": "CreateStream",
  "name": "newStream",
  "uri": "user1/newStream",
  "status": {
    "color": "#ff1100"
  }
}

RESPONSE {
  "type": "Stream",
  "correlation": 0,
  "id": "5543189230048561ad7aeb1a",
  "name": "newStream",
  "uri": "user1/newStream",
  "created": 1430460562460,
  "updated": 1430460562512,
  "status": {
    "color": "#ff1100",
    "created": 1430460562512,
    "poster": "553d7e6b30043b38ce3f704e"
  },
  "owner": "553d7e6b30043b38ce3f704e"
}

Errors

`DeleteStream`

{
    "type": "DeleteStream",
    "uri": STREAM_URL
}

Delete a stream by uri.

Example

SEND {
  "type": "DeleteStream",
  "uri": "user1/stream1"
}

RESPONSE {
  "type": "Stream",
  "correlation": 0,
  "id": "553d7e6f30043b38ce3f7050",
  "name": "stream1",
  "uri": "user1/stream1",
  "created": 1430093423080,
  "updated": 1430456148918,
  "status": {
    "color": "#333333",
    "created": 1430456148918,
    "poster": "553d7e6b30043b38ce3f704e"
  },
  "owner": "553d7e6b30043b38ce3f704e"
}

Errors

Stream does not exist.
User does not own stream.
Stream is a root stream.

`GetStatus`

{
    "type": "GetStatus",
    "of": STREAM_URL
}

Gets the current status of a stream.

Example

SEND {
  "type": "GetStatus",
  "of": "user1/stream"
}

RESPONSE {
  "type": "StreamStatus",
  "uri": "user1/stream",
  "status": {
    "color": "#0000ff",
    "created": 1429160419760,
    "poster": "552f24f33004785713de674e"
  }
}

Errors

The target stream does not exist.

`SetStatus`

{
  "type": "SetStatus",
  "of": STREAM_URL,
  "status": {
    "color": #COLOR_IN_HEX
  } 
}

Set the status of a stream. Requires user authorization

Example

SEND {
  "type": "SetStatus",
  "of": "user1/stream",
  "status": {
    "color": "#ff0000"
  }
}

RESPONSE {
  "type": "StreamStatus",
  "uri": "user1/stream",
  "status": {
    "color": "#ff0000",
    "created": 1429160419760,
    "poster": "552f24f33004785713de674e"
  }
}

Errors

The target stream does not exist.
The user does not have permission to edit the stream.
Invalid data was provided.
The status color was invalid

`GetChildren`

{
  "type": "GetChildren",
  "of": PARENT_STREAM_URI,
  ?"query": NAME_SEARCH_STRING,
  ?"limit": INT,
  ?"offset": INT
}

Gets a list of children of the stream. An optional query may be provided to filter the child stream by name. Otherwise returns children order by updated time.

Example

SEND {
  "type": "GetChildren",
  "of": "toastmastergeneral"
}

RESPONSE {
  "type": "StreamChildren",
  "url": "toastmastergeneral",
  "children": [{
    "id": "553dc3c630043b38ce3f7056",
    "name": "Toasthalla",
    "uri": "toastmastergeneral/toasthalla",
    "created": 1430111174510,
    "updated": 1430111174510,
    "status": {
      "color": "#dda520",
      "created": 1430111174510,
      "poster": "553d7e6b30043b38ce3f704e"
    },
    "tags": [{"tag": "sotoast"}, {"tag": "goldenbrown"}, {"tag": "challahorgy"}],
    "owner": "553d7e6b30043b38ce3f704e"
  }, {
    "id": "553dc3c130043b38ce3f7054",
    "name": "Strategic Butter Reserve",
    "uri": "toastmastergeneral/strategic+butter+reserve",
    "created": 1430111169478,
    "updated": 1430111169478,
    "status": {
      "color": "#111111",
      "created": 1430111169478,
      "poster": "553d7e6b30043b38ce3f704e"
    },
    "tags": [{"tag": "toastworldproblems"}],
    "owner": "553d7e6b30043b38ce3f704e"}]
}

Errors

Stream does not exist.

GetChild

Look up a child by id. Can be used to check the existence of a child.

Example

SEND {
  "type": "CreateChild",
  "of": "toastmastergeneral",
  "child":  "toastmastergeneral/toasthalla"
}

RESPONSE {
  "type": "StreamChild",
  "uri": "toastmastergeneral",
  "child":{
    "id": "553dc3c630043b38ce3f7056",
    "name": "Toasthalla",
    "uri": "toastmastergeneral/toasthalla",
    "created": 1430111174510,
    "updated": 1430111174510,
    "status": {
      "color": "#dda520",
      "created": 1430111174510,
      "poster": "553d7e6b30043b38ce3f704e"
    },
    "tags": [{"tag": "sotoast"}, {"tag": "goldenbrown"}, {"tag": "challahorgy"}],
    "owner": "553d7e6b30043b38ce3f704e"
  }
}

Errors

Stream does not exist.
Child does not exist.

CreateChild

Register a new child. Requires authorization.

This does not create a child stream, only registers an existing child with a parent stream. Streams are automatically registered as children with their hierarchical parent when created.

Example

SEND {
  "type": "CreateChild",
  "of": "toastmastergeneral",
  "child":  "jonny/cakes"
}

RESPONSE {
  "type": "StreamChild",
  "uri": "toastmastergeneral",
  "child": {
    "id": "552f25793004785713de6750",
    "name": "Cakes",
    "uri": "jonny/cakes",
    "created": 1429153145591,
    "updated": 1429160419760,
    "status": {
      "color": "#0000ff",
      "created": 1429160419760,
      "poster": "552f24f33004785713de674e"
    },
    "owner": "552f24f33004785713de674e"
  }
}

Errors

User does not have permission to edit parent stream.
Stream does not exist.
Requested child stream does not exist.
Parent cannot be its own child.
The parent has too many children.

DeleteChild

Delete child. Requires authorization.

This only removes the parent child relationship, it does not delete the child stream. Returns the deleted child.

Errors

User does not have permission to edit parent stream.
Parent does not exist.
Child does not exist.
Cannot remove hierarchical child. For example, the stream sub1 at user/sub1 cannot be removed as a child of user.

GetTags

Gets the tags of a stream.

Example

SEND {
  "type": "GetTags",
  "of": "toastmastergeneral/bread+stockpile"
}

RESPONSE {
  "type": "StreamTags",
  "url": "toastmastergeneral/bread+stockpile",
  "tags": [
    {"tag": "sotoast"},
    {"tag": "goldenbrown"},
    {"tag": "challahorgy"}]
}

Errors

The stream does not exist.

SetTags

Sets the tags of a stream, overwriting the existing tags. Requires authorization. Returns the set of normalized tags values.

Example

SEND {
  "type": "SetTags",
  "of": "toastmastergeneral/bread+stockpile",
  "tags": [
    {"tag": "RYE"},
    {"tag": "Pumpernickel"},
    {"tag": "Challahorgy"}]

RESPONSE {
  "type": "StreamTags",
  "url": "toastmastergeneral/bread+stockpile",
  "tags": [
    {"tag": "rye"},
    {"tag": "pumpernickel"},
    {"tag": "challahorgy"}]
]

Errors

The stream does not exist.
User does not have permission to edit stream.
Too many tags.
Invalid tag data.

GetTag

Lookup a specific tag on a stream.

Example

SEND {
  "type": "SetTag",
  "of": "toastmastergeneral/bread+stockpile",
  "tag": "RYE"
}

RESPONSE {
  "type": "StreamTag",
  "url": "toastmastergeneral/bread+stockpile",
  "tag": "rye"
}

Errors

Stream does not exist.
Tag does not exist

SetTag

Add a specific tag to a stream. Requires authorization. Noop if the tag already exists

Example

SEND {
  "type": "SetTag",
  "of": "toastmastergeneral/bread+stockpile",
  "tag": "GoldenBrown"
}

RESPONSE {
  "type": "StreamTag",
  "url": "toastmastergeneral/bread+stockpile",
  "tag": "goldenbrown"
}

Errors

The stream does not exist.
User does not have permission to edit stream.
Too many tags.
Invalid tag name.

DeleteTag

Remove a tag from a stream. Requires authorization. Returns the deleted tag.

Example

SEND {
  "type": "DeleteTag",
  "of": "toastmastergeneral/bread+stockpile",
  "tag": "rye"
}

RESPONSE {
  "type": "StreamTag",
  "url": "toastmastergeneral/bread+stockpile",
  "tag": "rye"
}

Errors

User does not have permission to edit stream.
The stream does not exist.
The tag does not exist.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Web Socket Response API

Basics

Responses

Correlation

Disabling Success Ack

Stream Operations

`GetStream`

GetStreams

`CreateStream`

`DeleteStream`

`GetStatus`

`SetStatus`

`GetChildren`

GetChild

CreateChild

DeleteChild

GetTags

SetTags

GetTag

SetTag

DeleteTag

Clone this wiki locally