JavaScript API

RestDB.io autogenerates a complete JavaScript API for your database.
 
To view the JavaScript API for your database, enter development mode and click the "API Doc" button.


The JavaScript API reflects your data schema. This makes it very easy to understand and to program against. The example below shows the API for a simple database with one Collection. Check out this blog post for a simple code example.

Database API setup
Create a new database api connection 
var db = new db("your-CORS-apikey-here | JWT token", options);


API key
A valid CORS enabled API key or a valid JWT token (options.jwt must be set to true). Read docs for instructions https://restdb.io/docs/apikeys-and-cors.

Options (object)
  • url: override database url, e.g. going through a proxy server
    logging: bool (default is false)
    realtime: bool (default is false)
  • jwt: bool (default false)

Include your JavaScript API library in a web page


To use the API in your web application include JQuery first, then include the API:

<script src="https://code.jquery.com/jquery-2.2.3.min.js"></script>
<script src="https://<databasename>.restdb.io/assets/js/eventsource.min.js"></script>
<script src="https://<databasename>.restdb.io/rest/_jsapi.js"></script>

Alternative without JQuery, using plain vanilla JavaScript, e.g. in React, Vue or Angular apps:

<script src="https://<databasename>.restdb.io/assets/js/eventsource.min.js"></script>
<script src="https://<databasename>.restdb.io/rest/_jsapi.js?plainjs=true"></script>

RestDB.io also generates a complete API documentation, using the same URL with a .doc extension produces a HTML documentation page like below:

Add a link to your API documentation by a link to the generated library:

<a href="https://<databasename>.restdb.io/rest/_jsapi.doc">

Mycollection (Example)

Description
var obj = new db.mycollection(properties);
Properties
Optional initial properties for a new instance of an mycollection, e.g. {"name": "Foo", "zip": 900, ...}

Mycollection properties

nametypedescription
obj['name']textData field description here
obj['zip']text
obj['employees']peopleLink to another collection
obj['address']text
obj['boss']peopleLink to another collection
obj['obj']json
obj['city']text

Instance methods

obj.save(callback)

obj.save(function(err, res){
  if (!err){
    // res is now the saved obj
  }
});

obj.delete(callback)

obj.delete(function(err, res){
  if (!err){
    // res is the ID of the deleted object
  }
});

obj.reload(callback)

obj.reload(function(err, res){
  if (!err){
    // res is now the reloaded object from the database
  }
});

obj.on(evt, callback)

obj.on("PUT", function(err, evt){
  if (!err){
    // PUT: evt.data contain the ID of the updated object, i.e. obj
    // DELETE: evt.data contain an array of IDs, of which one is this obj
  }
});

obj.projects.addChild(childobj, callback)

var child = new db.project({... properties ...});
obj.projects.addChild(child, function(err, res){
  if (!err){
    // res is the saved child
  }
});

obj.projects.getChild(callback)

obj.projects.getChild(function(err, res){
  if (!err){
    // res is an array of child project objects
  }
});

Collection methods

db.mycollection.find(query, [hints], callback)

var query = {}; // get all records
var hints = {"$max": 10, "$orderby": {"_id": -1}}; // top ten, sort by creation id in descending order
db.mycollection.find(query, hints, function(err, res){
  if (!err){
    // res is an array of mycollection objects
  }
});

db.mycollection.getById(ID, callback)

db.mycollection.getById("570e4661edb62e6a00000000", function(err, res){
  if (!err){
    // res is a mycollection instance
  }
});

Collection events

db.mycollection.on(evt, callback)

db.mycollection.on("POST", function(err, evt){
  if (!err){
    // res evt contains data about event
    // PUT:    {event: "put", collection: "the-collection-name", data: "ID"}
    // POST:   {event: "post", collection: "the-collection.name", data: {_id: "ID", ...}}
    // DELETE: {event: "delete", collection: "the-collection-name", data: ["ID1", "ID2", ...]}
  }
});


Subscribe to Database events in realtime

Note: To use the realtime features set options parameter to {realtime: true}. You must also add realtime access to the API-key you use. You do this in the "Manage Users and Settings" section of your database.

Database events (if options.realtime = true)
db.on(event, callback)
Predefined events
  • "CONNECT"
  • "DISCONNECT"
  • "POST"
  • "PUT"
  • "DELETE"
Subscribe to "PUT" 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", ...]}
}

Publish / Subscribe to custom events

Subscribe to custom Messages from applications
db.on("<your_message>", function(error, eventdata){
  // eventdata format: {event: "<your_message>", data: {...}}
}
Publish custom events
db.publish("<your_message>", {"answer": 42}, function(error, result){
  // if not error result is {"message": "OK"}
}