Backend API Reference

Pub/Sub subscriptions

PUT /v1/connection/(str: conn_id)/subscriptions/(path: topic)

Subscribe client with conn_id to specific topic topic.

Request body is not used.

Client will receive topic with / substituted with ., for instance the channel/general topic will become channel.general in client message.

Example:

PUT /v1/connection/nb9NC-HpR/subscriptions/channel/general HTTP/1.1
Host: example.com

HTTP/1.1 204 No Content
Content-Length: 0
DELETE /v1/connection/(str: conn_id)/subscriptions/(path: topic)

Unsubscribe client with conn_id from specific topic.

Request body is not used.

Example:

DELETE /v1/connection/nb9NC-HpR/subscriptions/channel/general HTTP/1.1
Host: example.com

HTTP/1.1 204 No Content
Content-Length: 0
POST /v1/publish/(path: topic)

Publish JSON message to all subscribed clients. See also front-messsage.

Request body must be a valid JSON.

Example:

POST /v1/publish/channel/general HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 26

{"message": "Hello World"}

HTTP/1.1 204 No Content
Content-Length: 0

Lattice Subscriptions

PUT /v1/connection/(str: conn_id)/lattices/(path: namespace)

Subscribe client with conn_id to lattice namespace namespace.

Example:

PUT /v1/connection/nb9NC-HpR/lattices/test-chat/rooms HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 223

{"shared": {
    "room1": {"last_message_counter": 123},
    "room2": {"last_message_counter": 245}},
 "private": {
   "132565": {
        "room1": {"last_seen_counter": 120},
        "room2": {"last_seen_counter": 245}}
}}

HTTP/1.1 204 No Content
Content-Length: 0

Note

Lattice name can’t start with swindon/ (or swindon. as seen in frontend. These lattices are reserved.

DELETE /v1/connection/(str: conn_id)/lattices/(path: namespace)

Unsubscribe client with conn_id from lattice namespace.

Example:

DELETE /v1/connection/nb9NC-HpR/lattices/test-chat/rooms HTTP/1.1
Host: example.com
Content-Length: 0

HTTP/1.1 204 No Content
Content-Length: 0
POST /v1/lattice/(path: namespace)

Publish an update to lattice namespace.

Example:

POST /v1/lattice/test-chat/rooms HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 308

{"shared": {
    "room1": {"last_message_counter": 123},
    "room2": {"last_message_counter": 245}},
 "private": {
   "7777": {
    "room1": {"last_seen_counter": 120},
    "room2": {"last_seen_counter": 245}},
   "8734": {
    "room1": {"last_seen_counter": 123},
    "room2": {"last_seen_counter": 24}}
}}

HTTP/1.1 204 No Content
Content-Length: 0

The shared attribute contains keys in the lattice that will be shared between users. The private part is keyed by a user id and contain same kind of object for each user.

Each key-value pair in that object is a CRDT variable-value. The type of the variable is defined by the suffix. The types of variables are defined in CRDT Types section.

There is one special key supported in private section (the plan is to add public expiration later too):

expires_in

A time after which entry will be automatically deleted on server-side. It’s duration string like “10 seconds”, “10s”, or “90 minutes” in a human-readable format

(this functionality is experimental)

Users Lattice

Users lattice, is a special lattice that is named swindon.user from the viewpoint of the server, but has different server-side API:

PUT /v1/connection/(str: conn_id)/users

Subscribe client with conn_id to swindon.user namespace and show they the status of specified users:

Example:

PUT /v1/connection/nb9NC-HpR/users HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 109

["7777", "8734"]

HTTP/1.1 204 No Content
Content-Length: 0
PUT /v1/user/(str: user_id)/users

Add all user ids sent in this request to all the connections of the user named user_id (which are subscribed to user status via call above).

In other words show users specified in the body of this request to user user_id (but only their connections that already subscribed to the swindon.user namespace).

Example:

PUT /v1/user/7777/users HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 109

["8734"]

HTTP/1.1 204 No Content
Content-Length: 0
DELETE /v1/connection/(str: conn_id)/users

Unsubscribe client with conn_id from lattice swindon.user.

Example:

DELETE /v1/connection/nb9NC-HpR/users HTTP/1.1
Host: example.com
Content-Length: 0

HTTP/1.1 204 No Content
Content-Length: 0

Parameters specification

The following table shows allowed character sets for corresponding URL componets.

Parameter Valid Characters
Topic, UserID a-zA-Z0-9:_/-
Namespace a-zA-Z0-9_/-
Connection ID a-zA-Z0-9_-

Valid topics/namespaces example:

valid/topic/value
valid-topic-value
valid_topic_value
still-valid-topic/value:1
1/2/3
valid/namespace

Invalid topics/namespaces:

not,a,valid,topic
topic.with.dots

API response status codes

In case of valid request (correct URL and valid data) endpoints respond with 204 No Content status code. This must be considered successful call.

Any of above endpoints call also respond with following codes signaling error:

  • 400 Bad Request

    May be returned in the following cases:

    • Request with body sent to endpoint that does not expect body.
    • Request without body sent to endpoint that expects body.
    • Request body is not valid JSON.
    • Request JSON body has invalid format (for lattice endpoints).

  • 404 Not Found

    May be caused by either invalid URL path (or one of its components) or unsupported request method.