RESTHeart

The leading REST API Server for MongoDB.

RESTHeart connects to MongoDB and opens data to the Web: Mobile and JavaScript applications can use the database via RESTful HTTP API calls.

For an example, check our AngularJs Notes Example Application.

Note: RESTHeart has been tested against MongoDB v 2.6, 3.0 and now is mainly tested with 3.2.

Built on strong foundations

• The API strictly follows the RESTful paradigm.
• Resources are represented with the HAL+json format.
• Built on top of Undertow web server.
• Makes use of few, best of breed libraries, check the pom.xml!

Rapid Development

• No server side development is required in most of the cases for your web and mobile applications.
• The Setup is simple with convention over configuration approach; Docker Container and Vagrant Box are available.
• Access Control and Schema Check are provided out of the box.

Production ready

• High quality Documentation and active development community.
• Severe Unit and Integration test suite, Code Check and Continuous Integration process.
• Commercial Support available from SoftInstigate, the company behind RESTHeart.

Fast & Light

• High throughput check the performance tests.
• Lightweight ~7Mb footprint, low RAM usage, starts in ~1 sec.
• Horizontally Scalable with Stateless Architecture and full support for MongoDB replica sets and shards.
• µService: it does one thing and it does it well.

Table of contents

• Documentation references
• An Example
• Installation
• How to run it
• Starter Guide
• How to build it
• Integration Tests
• Maven dependencies
• Snapshot builds

Documentation References

• Web site: http://restheart.org

• Issues: https://softinstigate.atlassian.net/projects/RH

• Documentation: https://softinstigate.atlassian.net/wiki/display/RH/Documentation

An Example

RESTHeart enables clients to access MongoDB via a HTTP RESTful API

In the following example, a web client sends an HTTP GET request to the /blog/posts URI and gets back the list of blog posts documents.

For more examples, check the API tutorial

Installation

RESTHeart can be installed on any OS supporting Java.

Complete instruction at Installation and Setup documentation section.

Docker container and Vagrant box are also available.

How to run it

Running RESTHeart requires Java 8

Download the latest release from github releases page, unpack the archive and just run the jar.

$ java -server -jar restheart.jar

You might also want to specify a configuration file:

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

the restheart.yml configuration enables authentication: users, roles and permission are defined in etc/security.yml

• Configuration file documentation
• Example configuration file restheart.yml
• Security documentation

Starter Guide

dbs and collections

get the list of dbs

GET /

get the list of the collections of a db

GET /<db>

Resources have properties and embedded data. The root embeds the existing dbs, dbs embed their collections.

create a db

PUT /db { "description": "my first db", "$currentDate" : {"creation_time": true}, "object.n": 1, "array.0": "item" }

Any write request can use the dot notation and update operators

update the properties of dbs and collections

PUT /db { "description": "my first db", "$currentDate" : {"update_time": true} }
PATCH /db { "$inc": {"object.n": 1 } }

Every write request has upsert semantic

PUT /db/coll { "description": "my first collection", "$currentDate" : {"update_time": true} }
PATCH /db/coll { "description": "my first collection", "" }

PUT upserts the whole property set, PATCH updates only the passed properties

delete dbs and collections

DELETE /db If-Match:<ETag>
DELETE /db/coll If-Match:<ETag>

The default configuration requires DELETE db/collection requests to pass the resource ETag using the If-Match header. See ETag section of the documentation.

create an index

PUT /db/collection/_indexes/index { "keys":{"name":1}, "ops":{"unique": true, "sparse": true} }

documents

create a documents

POST /db/coll { "number": 1, "array": ["a", "b"], "object": { "number": 1, "string": "happy coding" } }

creating a document without passing the _id property will result in with a new ObjectId

POST /db/coll { "number": 1, "array": ["a", "b"], "object": { "number": 1, "string": "happy coding" } }
PUT /db/coll/docid

PUT /db/coll/1

_id property

PUT /db/coll/1?doc_id=number

query documents

aggregation operations

validating data with json schema

shard keys

How to build it

Building RESTHeart requires Maven.

Clone the repository and update the git submodules (the HAL browser is included in restheart as a submodule):

$ git submodule update --init --recursive

Build the project with Maven:

$ mvn clean package

Integration tests

Optionally you can run the integration test suite. Make sure mongod is running on localhost on default port 27017 without authentication enabled, i.e. no --auth option is specified.

$ mvn verify -DskipITs=false

Maven dependencies

RESTHeart's releases are available on Maven Central.

If you want to embed RESTHeart in your project, add the dependency to your POM file:

<dependencies>
    <dependency>
        <groupId>org.restheart</groupId>
        <artifactId>restheart</artifactId>
        <version>1.1.4</version>
    </dependency>
</dependencies>

Note that RESTHeart v 1.1.4 is the first release officially available on Maven Central.

Snapshot builds

Snapshots are available on:

https://oss.sonatype.org/content/repositories/snapshots/org/restheart/restheart/

If you want to build your project against a development release, first add the SNAPSHOT repository:

 <repositories>
    <repository>
         <id>restheart-mvn-repo</id>
         <url>https://oss.sonatype.org/content/repositories/snapshots</url>
         <snapshots>
             <enabled>true</enabled>
             <updatePolicy>always</updatePolicy>
         </snapshots>
    </repository>
 </repositories>

Then include the SNAPSHOT dependency in your POM:

<dependencies>
    <dependency>
        <groupId>org.restheart</groupId>
        <artifactId>restheart</artifactId>
        <version>1.2.0-SNAPSHOT</version>
    </dependency>
</dependencies>

Development releases are continually deployed to Maven Central by Travis-CI.

Made with ❤️ by The SoftInstigate Team. Follow us on Twitter.