RestDB.io can act as a real-time messaging hub for your application. You can use the real-time API from web clients and servers, actually any client that can connect to your database using the HTTP EventSource API.
Web clients should use the JavaScript API for you database. Server to server scenarios can use the REST API directly via cURL (or similar).
Read this blog post with a complete code example for a real-time chat.
Real-time messages are switched off by default for security reasons. There are two ways to enable them:
In "Developer Mode", select the "Settings" tab and enter the following configuration:
{
"realtime":{
"global": true
}
}
In the "Users and Settings" of your database, select the "API" tab and create/edit a Web API key. In the bottom of the dialog, select "Real-time events". Now you can add "channels" and add the REST messages you want to listen to using this API key. The format is <METHOD>:<COLLECTION>, so if you want to listen to "POST" events on the "company" collection, you add POST:company to the list of events.
For instructions on how to use realtime with external users (JWT authenticated), check out the
users and roles documentation.
The server-sent event API is contained in the EventSource interface; to open a connection to the server to begin receiving events from it, create a new EventSource object, specifying the URI to the database realtime event stream. For example:
var evtSource = new EventSource('https://mydatabase-fe21.restdb.io/realtime?apikey=xxxxxx');
To listen for incoming messages from your database you must listen for typed events, using the addEventListener() method:
evtSource.addEventListener('post', function (e) {
// do something with e.data, e.g. JSON.parse(e.data)
}, false);
evtSource.addEventListener('put', function (e) {
// do something with e.data
}, false);
// listen for message publishing
evtSource.addEventListener('publish', function (e) {
// do something with e.data
}, false);
https://developer.mozilla.org/en-US/docs/Web/API/EventSource
RestDB.io lets you subscribe to Database events in realtime. Create a new database api connection using the auto generated JavaScript API for your database (read the JavaScript API docs here). Read this blog post about a chat application with a complete code example.
var db = new.db("your-CORS-apikey-here | JWT token", {realtime: true});
Note: You must also add realtime access to the web API-key you use. You do this in the "Manage Users and Settings" section of your database.
The API for realtime messaging consists only of two methods:
| Method | Description |
|---|---|
db.on(event, cb) | Listen to database events (POST, PUT, PATCH, DELETE, CONNECT, DISCONNECT, RECONNECT) or custom events (<EVENTNAME>) |
db.publish(event, data, cb) | Publish custom events (<EVENTNAME>) |
db.on(event, callback)
Subscribe to "PUT" or "PATCH" database operations
db.on("PUT", function(error, eventdata){
// eventdata format: {event: "put", collection: "the-collection-name", data: "ID"}
...
}
Subscribe to "POST" database operations
db.on("POST", function(error, eventdata){
// eventdata format: {event: "post", collection: "the-collection.name", data: {_id: ID, ...}}
...
}
Subscribe to "DELETE" database operations
db.on("DELETE", function(error, eventdata){
// eventdata format: {event: "delete", collection: "the-collection-name", data: ["ID1", "ID2", ...]}
...
}
The JavaScript API handles all connect and reconnect to the database automatically. However, you can also subscribe to these events with the following code.
Subscribe to "CONNECT" client state
db.on("CONNECT", function(){
// flash green stuff to indicate that we're on-line :)
...
}
Subscribe to "DISCONNECT" client state
db.on("DISCONNECT", function(){
// flash red stuff to indicate that we're off-line :(
// perhaps you lost the wifi, 4G or the server dropped out?
...
}
Subscribe to "RECONNECT" client state
db.on("RECONNECT", function(){
// flash green stuff to indicate that we're back in business ;-)
...
}
RestDB.io lets you publish/subscribe custom events that are not related to data changes in your database.
Publish custom events
db.publish("GOAL", {"match": 223, "value":"3-0"}, function(error, result){
// if not error result is {"message": "OK"}
...
}
Subscribe to custom Messages from applications
db.on("GOAL", function(error, eventdata){
// eventdata format: {event: "GOAL", data: {...}}
...
}
All RestDB.io databases has an endpoint for realtime messages. You can connect to the url with any http-compatible libraries (with EventSource support). In this example we'll be using curl from the command line.
https://dbname-f16c.restdb.io/realtime
To subscribe to event messages use the GET method. To publish event messages use the POST method.
The example output from a realtime session using curl is shown below:
curl -i -H "Content-Type: application/json" -H "x-apikey: your-api-key-here" -X GET 'https://dbname-f16c.restdb.io/realtime'
HTTP/1.1 200 OK
...
:
retry: 2000
data: {"channel":"init","data":{}}
event: ping
data: 2016-07-06T13:22:01.130Z
id: 9
event: put
data: {"event":"put","collection":"customer","data":"577cf185e2039b0900000016"}
retry: 10000
The example above shows how the client connects to the endpoint with a GET request. The realtime endpoint sends some headers first, most importantly the connection: keep-alive header. Then it sends some initial metadata to indicate that everything is ok. After a while the server sends an event to the client. In this example it's a PUT event with a data payload about the actual event in the database.
In a similar way we can publish custom events to the realtime API using a POST method.
The example below shows a realtime event published with using HTTP.
curl -i -H "Content-Type: application/json" -H "x-apikey: you-api-code-here" -X POST -d '{"event":"boing","data":{"name":"value"}}' 'https://dbname-f16c.restdb.io/realtime'
HTTP/1.1 200 OK
...
{"message":"OK"}
Node.js
https://github.com/aslakhellesoy/eventsource
Python
https://pythonhosted.org/eventsource/
Swift
