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.