RESTHeart

The leading REST API Server for MongoDB, created by SoftInstigate.

Table of Contents

• Summary
• Test with Docker
• Starter Guide
• An Example
• Manual Installation
• How to Run RESTHeart
• How to Build It
• Integration Tests
• Maven Dependencies
• Snapshot Builds

Summary

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 of how RESTHeart works, check our sample AngularJS notes application.

Note: We've tested RESTHeart against MongoDB v. 2.6 and 3.0. We now test it mainly with 3.2 and 3.4.

For detailed information, visit RESTHeart's website, issues tracker and detailed documentation wiki.

Built on a Solid Foundation

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

Rapid Development

• RESTHeart typically requires no server side development for your web and mobile applications.
• The setup is simple, with a convention over configuration approach. We've provided a Docker container and Vagrant box.
• Access Control and Schema Check are provided out of the box.

Production-Ready

• Comes with high-quality, updated documentation and an active development community.
• Includes a severe unit and integration test suite, code check and continuous integration process.
• SoftInstigate provides commercial support.

Fast & Light

• High throughput: Check the performance tests.
• Lightweight: ~10Mb footprint, low RAM usage, and starts in ~1 sec.
• Horizontally scalable with a stateless architecture and full support for MongoDB replica sets and shards.
• µService: It does one thing, and it does it well.

Test with Docker

If you're running a Docker service locally, you can be on your way with RESTHeart and MongoDB in just few minutes. We've included a Docker folder with Dockerfile and docker-compose.yml files, plus a specific restheart.yml configuration in the Docker/etc folder. The build.sh bash script compiles the source code and builds the Docker image.

Steps:

$ cd Docker
$ ./build.sh
$ docker-compose up -d && docker-compose logs -f

Finally, point your browser to http://localhost:8080/browser/ using the id admin and password changeit when prompted for authentication.

By default, the MongoDB instance started by docker-compose does not use any named storage, so if you remove the container you might lose all your data. For more info, please read the comments in the docker-compose.yml file to enable a named data volume, and the section on managing data in containers.

If you have cloned from master branch, you should notice from the logs that RESTHeart's running version is the same as the POM's version (e.g. 3.1.0-SNAPSHOT).

Properties

{
  "_size": 0,
  "_total_pages": 0,
  "_returned": 0,
  "_restheart_version": "3.1.0-SNAPSHOT",
  "_type": "ROOT"
}

This permits a quick test cycle of new releases. Remember to clean up things and remove all containers before exiting:

$ docker-compose stop
$ docker-compose rm

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 retriees the list of blog-post documents:

For more examples, check the API tutorial.

Manual Installation

You can install RESTHeart on any OS that supports Java 8. Visit the Installation and Setup documentation section for instructions.

How to Run RESTHeart

Download the latest release from the GitHub releases page, unpack the archive, and 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

How to Build It

Building RESTHeart requires Maven.

Clone the repository and update the git submodules. RESTHeart includes the HAL browser 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.

Stable releases are available at:

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

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>2.0.2</version>
    </dependency>
</dependencies>

Snapshot Builds

Snapshots are available at Sonatype. 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>3.0.0-SNAPSHOT</version>
    </dependency>
</dependencies>

We continually deploy development releases to Maven Central with Travis-CI.

---

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