RESTHeart - Web API Server for MongoDB.

Table of Contents

• Table of Contents
• Summary
• Setup
• Configuration
• Security
• How to Build
• Integration Tests
• Maven Dependencies
  • Snapshot Builds
  • Maven Site
• Continuous Integration

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.

For more information, visit RESTHeart's website and documentation.

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 git@github.com: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.

NOTE: for security reasons RESTHeart by default binds only on localhost, so it won't be reacheable from external systems unless you edit the configuration. To accept connections from everywhere, you must set at least the http listener in the etc/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.

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

$ git clone git@github.com:SoftInstigate/restheart.git
$ cd restheart
$ docker-compose up -d

WARNING: by default the docker-compose.yml binds RESTHeart to port 8080 on address 0.0.0.0, thus your instance can be potentually reachable by external clients.

Again, point your browser to the tutorial for more.

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.

---

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