Documentation

Create databases and use the powerful REST API.

Visit the blog for in-depth articles and tutorials.

Realtime Messaging

RestDB.io can act as a Realtime messaging hub for your application. You can use the realtime 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).

Realtime messaging using the JavaScript API

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.

API

The API for realtime messaging consists only of two methods:

MethodDescription
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>)

Subscribe to database events

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", ...]}
            ...
    }

Connection states

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 ;-)
            ...
    }

Publish / Subscribe to custom events

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: {...}}
            ...
    }

Realtime messaging using HTTP and cURL

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"}

Links to EventSource API client libraries

Node.js

https://github.com/aslakhellesoy/eventsource

Python

https://pythonhosted.org/eventsource/

Swift

https://github.com/inaka/EventSource