Using Sockets

Sockets and WebSockets provide full-duplex communications channels over a single TCP connection. It is recommended that you secure socket connections with TLS / SSL.

The Xively Socket Server is designed to make it easier to interact with Xively in ‘chatty’ situations where HTTP/HTTPS communications would be too onerous – watching for a change to a parameter, or reading/writing frequently for example.

The Socket Server includes specific methods to make clients which require real-time ‘push’ notifications as easy as possible. Because it requires only a single connection to be established, it is also a good way to write clients which have more restricted network capabilities.

Note: Your client might occasionally be disconnected (due to network instability for instance), so for the best results, your client should be able to automatically reconnect.

There are three types of Socket Server requests:

  1. HTTP Methods
  2. Subscribe
  3. Unsubscribe

The Xively socket-server accepts the following incoming connections:

Connection Type Server Port
Websocket api.xively.com 8080
TCP Socket api.xively.com 8081

Request Syntax

Once connected the protocol is HTTP wrapped in JSON

{
  "method" : "put",
  "resource" : "/feeds/504",
  "params" : {},
  "headers" : {"X-ApiKey":"abcdef123456"},
  "body" :
    {
      "version" : "1.0.0",
      "datastreams" : [
        {
          "id" : "0",
          "current_value" : "980"
        },
        {
          "id" : "1",
          "current_value" : "-261"
        }
      ]
    },
  "token" : "0x12345"
}

// Response: {
  "token" : "0x12345",
  "status" : 200,
  "resource" : "/feeds/504"
}

Method

One of the standard HTTP methods (get, put, post, delete), or one of the Socket Server’s extended-HTTP methods (subscribe, unsubscribe). For example:

// For a GET request "method" : "get"
// For a SUBSCRIBE request "method" : "subscribe"

Resource

The resource we want to access. It should start with a leading-slash. For example:

// For Feed 504, Datastream 0 "resource" : "/feeds/504/datastreams/0"


If method is a standard HTTP method (get, put, post, delete), the resource string can include the desired format. For example:

// For Feed 504 "resource" : "/feeds/504"

Params

The query-params to pass along to the resource. For example:

// To get Feed 504, Datastream 0, with a specific duration and interval "resource" : "/feeds/504/datastreams",
"params" :
  {
    "duration" : "2hours",
    "interval" : "6"
  }

Headers

The HTTP headers to pass along with the request. For example:

// To pass your Xively Api Key: "headers" :
  {
    "X-ApiKey" : "YOUR_API_KEY"
  }

Body

The HTTP body JSON to pass along with the request. For example:

// For updating a Datastream: "body" :
  {
    "version" : "1.0.0",
    "datastreams" : [
      {
        "id" : "streamId1",
        "current_value" : "value1"
      },
      {
        "id" : "streamId2",
        "current_value" : "value2"
      }
    ]
  }

Token

This is an arbitrary string, and generated by the client. It is not necessary to include this in your requests. However, because the Socket Server may respond to requests asynchronously (i.e. out of order), the request token is included in the the Socket Server’s response in order to help the client associate requests with responses. For example:

// An arbitrary incrementing counter "token" : "123"
// A pointer to a callback function "token" : "0xabc456"