wangmb / restheart Goto Github PK

RESTHeart - Web API Server for MongoDB.

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

RESTHeart is a REST microservice for MongoDB.

RESTHeart connects to MongoDB and opens its data to the Web. Clients, such as mobile and JavaScript apps, can access the database via a simple API based on JSON messages.

With RESTHeart teams can focus on building Angular, React, Vue, iOS or Android applications, because most of the server-side logic usually necessary for CRUD (Create, Read, Update, Delete) operations is automatically handled, without the need to write any code except for the client logic.

For example, to insert data in MongoDB developers model client-side JSON documents and then execute POST operations via HTTP to RESTHeart: no more need to deal with complicated server-side code and database drivers in Java, JavaScript, PHP, Ruby, Python, etc.

For these reasons, RESTHeart is widely used by freelancers, Web agencies ans System Integrators with deadlines, because it allows them to focus on the most creative parts of their work.

For more ideas have a look at the collection of common use cases.

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.

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 = '*'

Refer to the configuration file for inline documentation.

Starting from RESTHeart v4, security has been extracted as a separate layer handled by restheart-security, which is a reverse proxy microservice for HTTP resources, providing Authentication and Authorization services.

Alternatively, you can put any HTTP reverse proxy in front of RESTHeart and delegate security to it. For an example of using NGINX as a reverse proxy on top of RESTHeart, have a look at this repository. Then it is possibile to configure NGINX to restrict access with HTTP Basic Authentication.

Building RESTHeart requires Maven and Java 11 or later.

Build the project with Maven:

$ mvn clean package

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.

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>

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>

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

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.

For more information, read the documentation.

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