RESTHeart: stop deploying and enjoy piping


RESTHeart: stop deploying and enjoy piping

15 January 2015  • SoftInstigate Team
Categories: en, technology  • Tags: restheart, mongodb

RESTHeart is the Open Source data REST API server for MongoDB. Despite this definition, not only it exposes the data, but also serves static resources and custom application logic. Everything goes through its simple yaml configuration file: this is what we call piping and it is easy and effective, so that you don’t have to deal with complex deployments anymore. And more exciting features are on the way… You can find the documentation at and fork it on

Get up and running in 5 minutes

If you still don’t have RESTHeart, please refer to get up and running documentation section to quickly get ready with a running instance.

You’ll need to start RESTHeart specifying a configuration file. The download package ships with an example: <RESTHEART_HOME>/etc/restheart.yml. To use it, execute the following command:

java -server -jar restheart.jar etc/restheart.yml

Data resources

Data resources are managed via the mongo-mounts configuration option.

The default configuration just pipes in any MongoDB resource so that the API client can, if authorized, request any db and any collection resource.

# Use mongo-mounts to bind URLs to MongoDB resources
  - what: "*"
    where: /

It is easy to reconfigure it, so that just some MongoDB resources are piped in.

Some examples

The following configuration pipes in the collections db.c1 and db.c2, binding them to the URIs /one and /two respectively. With this configuration, RESTHeart does not expose any other MongoDB resource.

  - what: /db/c1
    where: /one
  - what: /db/c2
    where: /two

The following configuration makes accessible just the document D of the collection C of the database DB binding it to the URI /just/a/document.

  - what: /DB/C/D
    where: /just/a/document

Static resources

The static resources are managed via the static-resources-mounts configuration option.

The default configuration just pipes in the HAL browser. Its HTML, CSS and JavaScript resources are embedded within the restheart.jar file and bound to the URI /browser.

The following yaml fragment is the corresponding configuration:

  - what: browser
    where: /browser
    welcome-file: browser.html
    secured: false
    embedded: true

Note that:

  • what: the directory path containing the static resources. Since these are embedded in the jar, this path is relative to the jar package root directory;
  • where: the URI where the resources are served;
  • welcome-file: the file to serve when the where URI is requested;
  • secured: true if the configured RESTHeart Access Manager, if any, should be used for these resources;
  • embedded true if the resources are embedded in the jar file, false if they are in the file system.

You can find another good example of piping static resources in the RESTHeart example blog application. This blog application uses the AngularJS MVC framework and RESTHeart as web server and data storage.

Its static-resources-mounts configuration section is:

  - what: app
    where: /blog
    welcome-file: index.html
    secured: false
    embedded: false

This tells RESTHeart to serve the resources located in the app directory that contains the AngularJS single page web application. These are be bound to the /blog URI.

Application logic

The application logic handlers are managed via the application-logic-mounts configuration option.

The default configuration pipes in two example application logic handlers. RESTHeart has a pipeline architecture where Java handlers are chained to serve the requests.

In order to provide additional application logic, custom handlers can be piped in and bound under the /_logic URI. The custom handler must extends the org.restheart.handlers.ApplicationLogicHandler class

  - what: org.restheart.handlers.applicationlogic.PingHandler
    where: /ping
    secured: false
      msg: "ciao from the restheart team"
  - what: org.restheart.handlers.applicationlogic.GetRoleHandler
    where: /roles/mine
    secured: false
      url: /_logic/roles/mine
      send-challenge: false
      idm-conf-file: ../etc/security-integrationtest.yml
  • PingHandler is bound to /_logic/ping and implements a simple ping service
  • GetRoleHandler is bound to /_logic/roles/mine and returns the current user authentication status and eventually its roles

For instance, the mentioned RESTHeart example blog application uses the GetRoleHandler (GETing the /_logic/roles/mine resource) to determine if the current user is logged in and show the login form eventually.

More to come

Stored queries

Release 0.9.9 will ship with the stored queries feature. This goes further in simplifying the “development” of the data API, allowing aggregation and map-reduce queries to be defined without any code development and even without touching the configuration file.

The stored queries are going to be defined as collection meta-data properties, and automatically made available to users. This approach is similar to the rels collection meta-data that makes possible defining relationships between collections so that document representations automatically include links to related documents.

For instance, the following store query makes the /db/coll/_queries/average resource available.

 rels: {...},
 queries: [
    uri: 'average',
    type: 'mapReduce',
    map: 'function() { emit(this.age) }',
    reduce: 'function(key, values)
    { return Array.avg(values)}' 

Stored JavaScript application logic

We recently received a valuable feedback from the community about adding support for the Nashorn embeddable JavaScript engine; you can check the discussion on GitHub.

This is a brilliant idea indeed! An embedded JavaScript engine would allow storing JavaScript application logic functions in MongoDB and binding their execution to specific URIs, following a similar approach than stored queries. For instance, validation functions as the user suggested but use cases are endless.

And, again, no complex deployment would be needed anymore; developers could just pipe logic in RESTHeart via REST calls!