RESTHeart - Web API Server for MongoDB.

Table of Contents

• Summary
• Setup
• Use Docker
• Configuration
• Security
• How to Build
• Integration Tests
• Maven Dependencies
  • Snapshot Builds
  • Maven Site
• Continuous Integration
• Full documentation

Summary

RESTHeart connects to MongoDB and opens data to the Web. Clients such as mobile and javascript apps can use the database via a simple RESTful API.

Setup

Download the latest release, then install and run MongoDB

Assuming that MongoDB is running on localhost on port 27017, then run RESTHeart as follows:

$ git clone [email protected]:SoftInstigate/restheart.git

$ cd restheart

$ java -jar restheart.jar etc/restheart.yml -e etc/dev.properties

RESTHeart will be up and running in few seconds, on HTTP port 8080. Then go to the tutorial, which uses REST Ninja as a client.

Security warning: by default RESTHeart mounts only a restheart database, to avoid to accidentally exposing the whole set of MongoDB databases publicly. This is controlled by the root-mongo-resource in the dev.properties file

...
# The MongoDb resource to bind to the root URI / 
# The format is /db[/coll[/docid]] or '*' to expose all dbs
root-mongo-resource = /restheart
...

It means that the root resource / is bound to the /restheart database. This database doesn't actually exist until you explicitly create it by issuing a PUT / HTTP command.

NOTE: for security reasons RESTHeart by default binds only on localhost, so it won't be reachable from external systems unless you edit the configuration. To accept connections from everywhere, you must set at least the http listener in the dev.properties file to bind to 0.0.0.0 like this:

http-listener = 0.0.0.0

Beware that you must stop and run RESTHeart again to reload a new configuration.

Use Docker

Alternatively, you can run RESTHeart with docker compose, which also starts a MongoDB container:

$ git clone [email protected]:SoftInstigate/restheart.git

$ cd restheart

$ docker-compose up -d

Again, point your browser to the tutorial for more.

WARNING: by default the docker-compose.yml binds RESTHeart to port 8080 on address 0.0.0.0, thus your instance can be potentially reachable by external clients. Besides, the config.properties file exposes all databases externally (not only restheart as the non-dockerized configration).

root-mongo-resource = '*'

Configuration

Refer to the configuration file for inline documentation.

Security

Starting from RESTHeart v4, security is handled by restheart-security.

How to Build

Building RESTHeart requires Maven and Java 11 or later.

Build the project with Maven:

$ mvn clean package

Integration Tests

To run the integration test suite, first make sure that mongod is running on localhost, on default port 27017 and without authentication enabled — i.e. no --auth option is specified.

$ mvn verify -DskipITs=false

Alternatively, if you have Docker, execute the following script:

$ ./bin/integration-tests.sh 

The script starts a Docker container running MongoDB and then execute the integration tests with Maven. It will clean-up the container at the end.

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>4.0.0</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>4.0.1-SNAPSHOT</version>
    </dependency>
</dependencies>

Maven Site

An automatically generated Maven Site for each build of the master branch is available at: http://softinstigate.github.io/restheart/

Continuous Integration

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

RESTHeart's public Docker images are also automatically built and pushed to Docker Hub. The latest tag for Docker images refers to the most recent SNAPSHOT release on the master branch.

Full documentation

For more information, read RESTHeart's [documentation.

---

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