RESTHeart - Rapid API Development with MongoDB

RESTHeart is a backend framework that transforms MongoDB into a API server. It can be extended with custom plugins to enhance its functionality

RESTHeart is designed for developing microservices, offering a robust and efficient solution built on top of Undertow.

Undertow is a high-performance web server written in Java, known for its flexibility and efficiency. It provides both blocking and non-blocking APIs based on NIO (Non-blocking I/O), making it suitable for a wide range of use cases from lightweight HTTP handlers to full-fledged servlet containers. Notably, Undertow is the default web server for the WildFly application server and replaces JBoss Web in JBoss EAP 7.

RESTHeart simplify and accelerate the development process, exposing the full MongoDB capabilities through REST, GraphQL and Websockets APIs with no backend code required. This cuts development time significantly. Supports MongoDB, Mongo Atlas, Percona Server, FerretDB, AWS DocumentDB, and Azure CosmosDB.

RESTHeart offers comprehensive authentication and authorization services, supporting various security schemes. It enables the management of users, roles and permissions directly in MongoDB collections, eliminating the need for backend code. This streamlined approach significantly reduces development time.

Documentation

The full documentation is available on restheart.org/docs.

If you want to play with the APIs, you can start from:

• The REST Data API Tutorial
• The GraphQL Data API Tutorial

Installation

Refer to the documentation sections Setup or Setup with Docker.

One-liner to run RESTHeart with Docker:

curl https://raw.githubusercontent.com/SoftInstigate/restheart/master/docker-compose.yml --output docker-compose.yml && docker compose up --attach restheart

Become a Sponsor

You can support the development of RESTHeart via the GitHub Sponsor program and receive public acknowledgment of your help.

Go and see available sponsor tiers.

The Framework

A plugin is a software component that extends the functionality of RESTHeart, allowing you to add additional features and capabilities to the basic API. RESTHeart supports the development of plugins in Java, Kotlin, and JavaScript.

There are four types of plugins in RESTHeart:

• Service: These plugins extend the API by adding web services.
• Interceptor: These plugins snoop and modify requests and responses at different stages of the request lifecycle.
• Initializer: These plugins execute initialization logic at system startup time.
• Provider: These plugins provide objects to other plugins via the @Inject annotation.

Additionally, it is also possible to develop security plugins to customize the security layer.

Build from source

Note: Building RESTHeart from scratch requires at least Java 17 and maven 3.6.

Build the fat JAR:

$ ./mvnw clean package -Pshade

To check the build version:

$ java -jar core/target/restheart.jar -v
RESTHeart Version 8.0.7-SNAPSHOT Build-Time 2024-07-17

You can then run it with (make sure to have mongod running on localhost:27017):

$ java -jar core/target/restheart.jar

Execute the integration tests suite

To execute the integration test suite:

$ ./mvnw clean verify

The verify goal starts the RESTHeart process and a MongoDB Docker container before running the integration tests.

To avoid starting the MongoDB Docker container, specify the system property -P-mongodb.

The integration tests use the MongoDB connection string mongodb://127.0.0.1 by default. To use a different connection string, specify the property test-connection-string.

The following example shows how to run the integration test suite against an instance of FerretDB running on localhost.

# run FerretDB
$ docker run -d --rm --name ferretdb -p 27017:27017 ghcr.io/ferretdb/all-in-one
# execute the integration tests
$ ./mvnw clean verify -DskipUTs -P-mongodb -Dtest-connection-string="mongodb://username:password@localhost/ferretdb?authMechanism=PLAIN" -Dkarate.options="--tags ~@requires-replica-set"

This example also specifies the karate options to skip tests tagged with requires-replica-set (FerretDB does not supports change stream and transactions) and -DskipUTs to skip the execution of unit tests.

Automatic snapshot builds

Snapshot builds are available from sonatype.org

Docker images of snapshots are also available:

$ docker pull softinstigate/restheart-snapshot:[commit-short-hash]

For commit short hash you need the first 7 digits of the hash, e.g.

$ git log

commit 2108ce033da8a8c0b65afea0b5b478337e44e464 (HEAD -> master, origin/master, origin/HEAD)
Author: Andrea Di Cesare <[email protected]>
Date:   Fri Oct 22 12:46:00 2021 +0200

    :bookmark: Bump to version 6.2.0-SNAPSHOT

...

The short hash is 2108ce0 and the docker pull command is therefore

$ docker pull softinstigate/restheart-snapshot:2108ce0

Community Support

• Open a issue on GitHub to report a specific problem.
• Ask technical questions on Stackoverflow.
• Chat with other users on Slack.
• Book a free 1-to-1 demo with us.

Sponsors

---

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