Server HTTP API¶
Danger
This is a documentation for Centrifugo v2. The latest Centrifugo version is v3. Go to the centrifugal.dev for v3 docs.
HTTP API is a way to send commands to Centrifugo. For example, server API allows publishing messages to channels.
Server HTTP API works on /api endpoint. It has very simple request format: this is a HTTP POST request with application/json Content-Type and with JSON command body.
In most cases though you can just use one of our available HTTP API libraries. In this chapter we will make an API method overview.
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>
Starting from Centrifugo v2.2.7 it's also possible to pass API key over URL query param. This solves some edge cases where it's not possible to use Authorization header. Simply add ?api_key=<YOUR API KEY> query param to API endpoint. Keep in mind that passing API key in Authorization header is a recommended way.
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 publishing data into a 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 unsubscribing user from a channel. params is an object with two keys: channel and user (user ID you want to unsubscribe)
{
"method": "unsubscribe",
"params": {
"channel": "CHANNEL NAME",
"user": "USER ID"
}
}
disconnect¶
disconnect allows disconnecting user by ID. params in an object with user key.
{
"method": "disconnect",
"params": {
"user": "USER ID"
}
}
presence¶
presence allows getting 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 getting 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 getting 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"
}
}, {
"data": {
"text": "hi!"
}
}
]
}
}
channels¶
channels allows getting 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"
]
}
}
Keep in mind that since channels API command returns all active channels it can be really heavy for massive deployments. At moment there is no way to paginate over channels list and we don't know a case where this could be useful and not error prone. At the moment we mostly suppose that channels command will be used in development process and in not very massive Centrifugo setups (with no more than 10k channels). Also channels command considered optional in engine implementations.
A better and scalable approach could be real-time analytics approach described here.
info¶
info method allows getting 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.