The directives and responses used by Pub/Sub sockets are JSON records. Standard HTTP status codes are used to indicate outcomes since their meanings are well known.
General Responses
Catch-all error response
An uncategorized error occurs on the server.
{
"seq": <client-supplied-unique-integer>,
"action": "<original-action>",
"code": 500,
"message": "Internal Error",
"details": "<detailed-error-description-which-may-contain-stack-traces>"
} |
Invalid format response
The directive was invalid (malformed JSON, bad attributes or types, etc.)
{
"seq": <client-supplied-unique-integer>,
"action": "<original-action>",
"code": 400,
"message": "Invalid Format",
"details": "<detailed-error-description-which-may-contain-stack-trace>"
} |
Invalid-request response
A request was received without a sequence whose format was invalid.
{
"action": "invalid-request",
"code": 400,
"message": "Invalid Request",
"details": "<detailed-error-description-which-may-contain-stack-trace>",
"bad_request": "<the-request-which-was-rejected>"
} |
Get the Session UUID
Whether the client sent in a session UUID as part of its authentication payload, or it was assigned a new session UUID automatically, they should be able to fetch it at any time via this directive.
Session-uuid request
{
"seq": <client-supplied-unique-integer>,
"action": "session-uuid"
} |
Successful response
{
"seq": <client-supplied-unique-integer>,
"action": "session-uuid",
"code": 200,
"uuid": "<session-uuid>"
} |
Subscribe to a Channel
Subscribe request
{
"seq": <client-supplied-unique-integer>,
"action": "subscribe",
"channel": "<channel-name>"
} |
Successful subscription response
{
"seq": <client-supplied-unique-integer>,
"action": "subscribe",
"code": 200,
"channels": [
<list-of-all-channel-subscriptions>
]
} |
Incorrect permissions response
A read perm-key was not supplied when the socket was established.
{
"seq": <client-supplied-unique-integer>,
"action": "subscribe",
"code": 401,
"message": "Not Authorized",
"details": "You do not have read permissions on this socket, and therefore cannot subscribe to channels."
} |
Unsubscribe from a Channel
Unsubscribe request
{
"seq": <client-supplied-unique-integer>,
"action": "unsubscribe",
"channel": "<channel-name>"
} |
Successful unsubscribe response
{
"seq": <client-supplied-unique-integer>,
"action": "unsubscribe",
"code": 200,
"channels": [
<list-of-all-channel-subscriptions>
]
} |
Incorrect permissions response
A read perm-key was not supplied when the socket was established.
{
"seq": <client-supplied-unique-integer>,
"action": "unsubscribe",
"code": 401,
"message": "Not Authorized",
"details": "You do not have read permissions on this socket. You have been unsubscribed from all channels."
} |
Subscription not found response
{
"seq": <client-supplied-unique-integer>,
"action": "unsubscribe",
"code": 404,
"message": "Not Found",
"details": "You are not subscribed to the specified channel."
} |
Unsubscribe from All Channels
Unsubscribe-all request
{
"seq": <client-supplied-unique-integer>,
"action": "unsubscribe-all"
} |
Successful unsubscribe-all response
{
"seq": <client-supplied-unique-integer>,
"action": "unsubscribe-all",
"code": 200,
"channels": [
<list-of-all-prior-channel-subscriptions>
]
} |
The channels field is the list of channels to which this client was subscribed before the unsubscribe-all directive was sent.
Incorrect permissions response
A read perm-key was not supplied when the socket was established.
{
"seq": <client-supplied-unique-integer>,
"action": "unsubscribe-all",
"code": 401,
"message": "Not Authorized",
"details": "You do not have read permissions on this socket. You have been unsubscribed from all channels."
} |
List All Subscriptions
Subscriptions listing request
{
"seq": <client-supplied-unique-integer>,
"action": "subscriptions"
} |
Successful subscriptions listing response
{
"seq": <client-supplied-unique-integer>,
"action": "subscriptions",
"code": 200,
"channels": [
<list-of-all-channel-subscriptions>
]
} |
Incorrect permissions response
A read perm-key was not supplied when the socket was established.
{
"seq": <client-supplied-unique-integer>,
"action": "subscriptions",
"code": 401,
"message": "Not Authorized",
"details": "You do not have read permissions on this socket, and therefore cannot list subscriptions."
} |
Publish a Message
Publish request
Publish requests are limited to 64KiB. Any request larger will result in the termination of the websocket connection.
{
"seq": <client-supplied-unique-integer>,
"action": "pub",
"chan": "<channel-name>",
"msg": "<message-body>",
"ack": <boolean>
} |
Publish acknowledgement
Only supplied if the publish request contained an ack
parameter set to true
{
"seq": <client-supplied-unique-integer>,
"action": "pub",
"code": 200,
"id": "<message-uuid>"
} |
Incorrect permissions response
A write perm-key was not supplied when the socket was established.
{
"seq": <client-supplied-unique-integer>,
"action": "pub",
"code": 401,
"message": "Not Authorized",
"details": "You do not have write permissions on this socket, and therefore cannot publish to channels."
} |
No subscriptions response
{
"seq": <client-supplied-unique-integer>,
"action": "pub",
"code": 404,
"message": "Not Found",
"details": "There are no subscribers to the specified channel, so the message could not be delivered."
} |
Message Format
Messages delivered to subscribers have the following format:
{
"id": "<message-uuid>",
"action": "msg",
"time": "<iso-8601-timestamp>",
"chan": "<channel-name">,
"msg": "<message-body">
} |