Skip to content

Server HTTP API

HTTP API is a way to send commands to Centrifugo.

Why we need API?

If you look at configuration options you see an option called publish defined on configuration top level and for channel namespace. When turned on this option allows browser clients to publish into channels directly. If client publishes a message into channel directly – your application will not receive that message (it just goes through Centrifugo towards subscribed clients). This pattern can be useful sometimes but in most cases you first need to send new event from client to backend over non-Centrifugo transport (for example via AJAX request in web application), then process it on application backend side – probably validate, save into main app database – and then publish into Centrifugo using HTTP API so Centrifugo broadcast message to all clients subscribed on channel.

Server API works on /api endpoint. It’s very simple to use: you just have to send POST request with JSON command to this endpoint.

In this chapter we will look at API protocol internals - for new API client library authors and just if you are curious how existing API clients work.

API request is a POST HTTP request with application/json Content-Type and JSON payload in request body.

API protected by api_key set in Centrifugo configuration. I.e. api_key must be added to config, like:

{
    ...
    "api_key": "<YOUR API KEY>"
}

This API key must be set in request Authorization header in this way:

Authorization: apikey <KEY>

It’s possible to disable API key check on Centrifugo side using api_insecure configuration option. Be sure to protect API endpoint by firewall rules in this case to prevent anyone in internet to send commands over your unprotected Centrifugo API. API key auth is not very safe for man-in-the-middle so recommended way is running Centrifugo with TLS (we are in 2018 in the end).

Command is a JSON object with two properties: method and params.

method is a name of command you want to call. params is an object with command arguments.

There are several commands available. Let’s investigate each of available server API commands.

publish

Publish command allows to publish data into channel. It looks like this:

{
    "method": "publish",
    "params": {
        "channel": "chat", 
        "data": {
            "text": "hello"
        }
    } 
}

Let’s apply all information said above and send publish command to Centrifugo. We will send request using requests library for Python.

import json
import requests

command = {
    "method": "publish",
    "params": {
        "channel": "docs", 
        "data": {
            "content": "1"
        }
    }
}

api_key = "YOUR_API_KEY"
data = json.dumps(command)
headers = {'Content-type': 'application/json', 'Authorization': 'apikey ' + api_key}
resp = requests.post("https://centrifuge.example.com/api", data=data, headers=headers)
print(resp.json())

The same using httpie console tool:

$ echo '{"method": "publish", "params": {"channel": "chat", "data": {"text": "hello"}}}' | http "localhost:8000/api" Authorization:"apikey KEY" -vvv
POST /api HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Authorization: apikey KEY
Connection: keep-alive
Content-Length: 80
Content-Type: application/json
Host: localhost:8000
User-Agent: HTTPie/0.9.8

{
    "method": "publish",
    "params": {
        "channel": "chat",
        "data": {
            "text": "hello"
        }
    }
}

HTTP/1.1 200 OK
Content-Length: 3
Content-Type: application/json
Date: Thu, 17 May 2018 22:01:42 GMT

{}

In case of error response object will contain error field:

$ echo '{"method": "publish", "params": {"channel": "unknown:chat", "data": {"text": "hello"}}}' | http "localhost:8000/api" Authorization:"apikey KEY"
HTTP/1.1 200 OK
Content-Length: 55
Content-Type: application/json
Date: Thu, 17 May 2018 22:03:09 GMT

{
    "error": {
        "code": 102,
        "message": "namespace not found"
    }
}

error object contains error code and message - this also the same for other commands described below.

publish command is the main command you need. Again - remember that we have client API libraries that can help you avoid some boilerplate we just wrote and help to properly handle error responses from Centrifugo.

Let’s look at other available commands:

broadcast

Similar to publish but allows to send the same data into many channels.

{
    "method": "broadcast",
    "params": {
        "channels": ["CHANNEL_1", "CHANNEL_2"],
        "data": {
            "text": "hello"
        }
    }
}

unsubscribe

unsubscribe allows to unsubscribe user from channel. params is an objects with two keys: channel and user (user ID you want to unsubscribe)

{
    "method": "unsubscribe",
    "params": {
        "channel": "CHANNEL NAME",
        "user": "USER ID"
    }
}

disconnect

disconnect allows to disconnect user by ID. params in an object with user key.

{
    "method": "disconnect",
    "params": {
        "user": "USER ID"
    }
}

presence

presence allows to get channel presence information (all clients currently subscribed on this channel). params is an object with channel key.

{
    "method": "presence",
    "params": {
        "channel": "chat"
    }
}

Example:

fz@centrifugo: echo '{"method": "presence", "params": {"channel": "chat"}}' | http "localhost:8000/api" Authorization:"apikey KEY"
HTTP/1.1 200 OK
Content-Length: 127
Content-Type: application/json
Date: Thu, 17 May 2018 22:13:17 GMT

{
    "result": {
        "presence": {
            "c54313b2-0442-499a-a70c-051f8588020f": {
                "client": "c54313b2-0442-499a-a70c-051f8588020f",
                "user": "42"
            },
            "adad13b1-0442-499a-a70c-051f858802da": {
                "client": "adad13b1-0442-499a-a70c-051f858802da",
                "user": "42"
            }
        }
    }
}

presence_stats

presence_stats allows to get short channel presence information.

{
    "method": "presence_stats",
    "params": {
        "channel": "chat"
    }
}

Example:

$ echo '{"method": "presence_stats", "params": {"channel": "public:chat"}}' | http "localhost:8000/api" Authorization:"apikey KEY"
HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
Date: Thu, 17 May 2018 22:09:44 GMT

{
    "result": {
        "num_clients": 0,
        "num_users": 0
    }
}

history

history allows to get channel history information (list of last messages published into channel).

params is an object with channel key:

{
    "method": "history",
    "params": {
        "channel": "chat"
    }
}

Example:

$ echo '{"method": "history", "params": {"channel": "public:chat"}}' | http "localhost:8000/api" Authorization:"apikey KEY"
HTTP/1.1 200 OK
Content-Length: 87
Content-Type: application/json
Date: Thu, 17 May 2018 22:14:10 GMT

{
    "result": {
        "publications": [
            {
                "data": {
                    "text": "hello"
                },
                "uid": "BWcn14OTBrqUhTXyjNg0fg"
            }, {
                "data": {
                    "text": "hi!"
                },
                "uid": "Ascn14OTBrq14OXyjNg0hg"
            }
        ]
    }
}

channels

channels allows to get list of active (with one or more subscribers) channels.

{
    "method": "channels",
    "params": {}
}

Example:

$ echo '{"method": "channels", "params": {}}' | http "localhost:8000/api" Authorization:"apikey KEY"
HTTP/1.1 200 OK
Content-Length: 27
Content-Type: application/json
Date: Thu, 17 May 2018 22:08:31 GMT

{
    "result": {
        "channels": [
            "chat"
        ]
    }
}

info

info method allows to get information about running Centrifugo nodes.

{
    "method": "info",
    "params": {}
}

Example:

$ echo '{"method": "info", "params": {}}' | http "localhost:8000/api" Authorization:"apikey KEY"
HTTP/1.1 200 OK
Content-Length: 184
Content-Type: application/json
Date: Thu, 17 May 2018 22:07:58 GMT

{
    "result": {
        "nodes": [
            {
                "name": "Alexanders-MacBook-Pro.local_8000",
                "num_channels": 0,
                "num_clients": 0,
                "num_users": 0,
                "uid": "f844a2ed-5edf-4815-b83c-271974003db9",
                "uptime": 0,
                "version": ""
            }
        ]
    }
}

Command pipelining

It’s possible to combine several commands into one request to Centrifugo. To do this use JSON streaming format. This can improve server throughput and reduce traffic travelling around.