Skip to main content

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 convenience. 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.

Authenticating requests

There are 3 options for authenticating via the http endpoint:

  1. Allow authData object on every request via the http connection endpoint in order to send the login credentials
authData: {
"username": "fred.flintstone@example.com",
"password": "y4b4d4b4d00"
},
body: [{
...
}]
  1. If your chosen auth strategy is webhook, a token can be sent in order to authenticate requests against the endpointUrl
{
"token": "aI2wYSh1FS_2WODD14bYZe1TfIyhAukl",
"body": [{...}]
}
  1. If you're using open auth, you can just go ahead and make requests without authentication data.

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 default to 1 MB. It can be adjusted on the http server configuration param maxMessageSize

Command request

ParameterTypeOptionalDescription
tokenstringtrueA valid auth token. Leave this out to use open auth.
authDataobjecttrueAuthentication credentials. Leave this out to use open auth.
bodyarrayfalseA non-empty array of commands.

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.
ParameterTypeOptionalDescription
resultstringfalse"SUCCESS" if all commands returned success, "PARTIAL_SUCCESS" if some failed, "FAILURE" otherwise.
bodyarrayfalseA non-empty array of message responses.

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.

Authentication request

If you need to check your credentials or retrieve a token from the authentication server use the authPath defined on the http server config

Example body:

{
"username": "johnny",
"password": "depp"
}

Example response:

{
"token": "",
"clientData": { he: "won" }
}
note

For generating the token a custom authentication handler must be used. An option is to use the same endpoint used for http authentication and let that service respond with a token when the connectionData has the authPath route

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.

ParameterTypeOptionalDescription
successbooleanfalseWhether the command executed successfully.
errorstringtrueA description of the error that occurred (if any).
errorTopicstringtrueThe topic of the error that occurred (if any) e.g. "record".
errorEventstringtrueThe event corresponding to the error (if any) e.g. "RECORD_NOT_FOUND".

Example response:

{
"success": true
}

Emitting an event

If successful response means that the request was permissioned correctly.

ParameterTypeOptionalDescription
topicstringfalseMust have value "event".
actionstringfalseMust have value "emit".
eventNamestringfalseThe name of the event subscription e.g. "frog".
dataJSONtrueA data payload e.g. { "obj": 3 } or "string".

Event example with numeric payload:

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

Reading a record

ParameterTypeOptionalDescription
topicstringfalseMust have value "record".
actionstringfalseMust have value "read".
recordNamestringfalseThe name of the record e.g. "cities/hamburg".

Example:

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

Non-standard response properties:

ParameterTypeOptionalDescription
versionintegertrueThe version of the record that was read.
datastringfalseThe current data that was read.

Example response:

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

Record head

Get the current version of a record.

ParameterTypeOptionalDescription
topicstringfalseMust have value "record".
actionstringfalseMust have value "head".
recordNamestringfalseThe name of the record e.g. "cities/hamburg".

Example:

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

Non-standard response properties:

ParameterTypeOptionalDescription
versionintegertrueThe version of the record that was read.

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.

ParameterTypeOptionalDescription
topicstringfalseMust have value "record".
actionstringfalseMust have value "write".
recordNamestringfalseThe name of the record e.g. "cities/hamburg".
pathstringtrueThe record path.
versionintegertrueThe version to be written. Defaults to -1 (force write).
dataJSONfalseThe data to be set. If no path is set, this must be an object.

Example:

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

Non-standard response properties:

ParameterTypeOptionalDescription
currentVersionintegertrueOn version conflict, the existing version.
currentDataJSONtrueOn version conflict, the existing data.

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.

ParameterTypeOptionalDescription
topicstringfalseMust have value "record".
actionstringfalseMust have value "delete".
recordNamestringfalseThe name of the record e.g. "cities/hamburg".

Example:

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

Making an RPC

Making a remote procedure call.

ParameterTypeOptionalDescription
topicstringfalseMust have value "rpc".
actionstringfalseMust have value "make".
rpcNamestringfalseThe name of the RPC to call.
dataJSONtrueThe RPC data argument.

Example request:

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

Non-standard response properties:

ParameterTypeOptionalDescription
dataJSONtrueOn success, RPC result.

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.

ParameterTypeOptionalDescription
topicstringfalseMust have value "presence".
actionstringfalseMust have value "query".
namesarraytrueArray of user names to query for presence.

Example request for all users:

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

Non-standard response properties:

ParameterTypeOptionalDescription
usersarrayfalseAn array of logged-in users.

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
}
}