Server HTTP API¶
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"
},
"uid": "BWcn14OTBrqUhTXyjNg0fg"
}, {
"data": {
"text": "hi!"
},
"uid": "Ascn14OTBrq14OXyjNg0hg"
}
]
}
}
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.