HTTP API

deepstream’s HTTP API provides access to a subset of the features available through the client libraries, by making simple requests to our secure HTTPS endpoint.

You can batch multiple fetches, updates and RPCs into a single request for convienience. Messages are counted on a per message basis, meaning a HTTP post that emits 3 events would count as three individual messages. However they do not affect your connection limit allowing thousands of devices to get or set your application on any plan.

Authentication

If your chosen auth strategy is webhook, the auth endpoint allows you to send authentication data and returns a session token that can then be used for requests.

If you’re using open auth, you can just go ahead and make requests without a token.

Auth Request

The body is specified For details on possible authentication data see the authentication overview.

Example body:

{
  "email": "fred.flintstone@example.com",
  "password": "y4b4d4b4d00"
}

Example request using cURL:

curl -X POST -H "Content-Type: application/json" -d '{
  "type": "email",
  "email": "fred.flintstone@example.com",
}
' "<YOUR HTTP AUTH URL>"

Auth Response

A successful response will have a 200 status code and a JSON body with the following properties:

Example response:

{
  "success": true,
  "token": "aI2wYSh1FS_2WODD14bYZe1TfIyhAukl",
  "clientData": {
    "client": "data"
  }
}

4XX status codes denote a failure, and will have a plaintext body containing the error message.

POST requests

POST requests allow you to batch an arbitrary number of updates or requests into a single message. Deepstream commands are encoded using the format defined below.

The maximum message size is 1 megabyte.

A token may be provided via the auth endpoint above.

Request

Example body:

{
  "token": "d9GKJkkdsjyKJh832s69sg9dberbs6fd",
  "body": [
    {
      "topic": "event",
      "action": "emit",
      "eventName": "stock-update",
      "data": {
        "apples": 40,
        "bananas": 100,
        "pears": 60
      }
    },
    {
      "topic": "record",
      "action": "read",
      "recordName": "balance"
    }
  ]
}

Example request using cURL:

curl -X POST -H "Content-Type: application/json" -d '{
  "token": "d9GKJkkdsjyKJh832s69sg9dberbs6fd",
  "body": [
    {
      "topic": "event",
      "action": "emit",
      "eventName": "stock-update",
      "data": {
        "apples": 40,
        "bananas": 100,
        "pears": 60
      }
    },
    {
      "topic": "record",
      "action": "read",
      "recordName": "balance"
    }
  ]
}
' "<YOUR HTTP URL>"

Response

A response with a 200 status code will have a JSON body in the following format:

• Note: a 200 response does not indicate that the messages succeeded. Be sure to check the “result” property in the response body.

Example response:

{
  "result": "PARTIAL_SUCCESS",
  "body": [
    {
      "success": true
    },
    {
      "success": false,
      "error": "Record read failed. Record \"balance\" could not be found.",
      "errorTopic": "record",
      "errorEvent": "RECORD_NOT_FOUND"
    }
  ]
}

Poorly formed requests and authentication errors will result in a plaintext response, with an appropriate status code in the range 400…499.

Command format

All commands must have the properties “topic” and “action”, which define the operation.

Responses are typically have the following standard fields. Any others are defined below.

Example response:

{
  "success": true
}

Emitting an event

If successful response means that the request was permissioned correctly.

Event example with numeric payload:

{
  "topic": "event",
  "action": "emit",
  "eventName": "lights-on",
  "data": 134.52
}

Reading a record

Example:

{
  "topic": "record",
  "action": "read",
  "recordName": "my-record"
}

Non-standard response properties:

Example response:

{
  "success": true,
  "version": 2,
  "data": {
    "foo": "bar"
  }
}

Record head

Get the current version of a record.

Example:

{
  "topic": "record",
  "action": "head",
  "recordName": "my-record"
}

Non-standard response properties:

Example response:

{
  "success": true,
  "version": 2
}

Creating or updating a record

Update a record. Records that do not already exist will be created.

The optional “path” property may be used to update only part of a record.

The “version” property may be used to ensure updates are not based on stale data. For an update to succeed, the version provided must be 1 greater than the current version (see head), otherwise a version conflict will occur.

Example:

{
  "topic": "record",
  "action": "write",
  "recordName": "users/123",
  "path": "firstname",
  "version": 6,
  "data": "Bob"
}

Non-standard response properties:

Example successful response:

{
  "success": true,
}

Example version conflict:

{
  "success": false,
  "error": "Record update failed. Version 6 exists for record \"users/123\".",
  "errorTopic": "record",
  "errorEvent": "VERSION_EXISTS",
  "currentVersion": 6,
  "currentData": {
    "firstname": "Alan",
    "lastname": "Smith"
  }
}

Deleting a record

Delete a record from the cache and storage.

Deletion will succeed even if the record does not exist, but storage and cache errors may occur.

Example:

{
  "topic": "record",
  "action": "delete",
  "recordName": "my-record"
}

Making an RPC

Making a remote procedure call.

Example request:

{
  "topic": "rpc",
  "action": "make",
  "rpcName": "add-two",
  "data": {
    "numA": 2,
    "numB": 5
  }
}

Non-standard response properties:

Example response:

{
  "data": 7,
  "success": true
}

Querying Online Users (Presence)

Presence allows you to retrieve a list of user ids that are online.

Note: HTTP requests do not contribute to presence updates or queries. These details relate only to WebSocket clients.

Example request for all users:

{
  "topic": "presence",
  "action": "query"
}

Non-standard response properties:

Example response when querying all users:

{
  "success": true,
  "users": [
    "ac65902c-13ea-469c-91e6-2cdc8c31136d", 
    "fba85ac8-02bd-98a7-bb42-b2526243b562", 
    "aba325bd-dd23-aba4-3390-02763477453e"
  ]
}

Example request for some users:

{
  "topic": "presence",
  "action": "query",
  "names": ["one", "two"]
}

Example response when querying specific users:

{
  "success": true,
  "users":{
    "one":true,
    "two":false
    }
}