RESTHeart (REpresentational State Transfer for Heart) is a lightweight, open-source Java-based web server that instantly transforms a MongoDB database into a RESTful API. Built on top of Undertow — a flexible and performant Java web server — and powered by the Reactive Streams API, RESTHeart eliminates the need to write boilerplate backend code. Developers can directly expose MongoDB collections and documents through standard HTTP endpoints, making it an ideal tool for rapid prototyping and scalable API-first development. I hope you like out RESTHeart introduction article!
1. Introduction to RESTHeart
RESTHeart serves as a middleware layer between MongoDB and HTTP clients. It is especially useful for developers who want to build microservices, Single Page Applications (SPAs), or backend services without writing custom controllers or business logic just to expose CRUD operations. With RESTHeart, any MongoDB collection becomes accessible via predictable RESTful routes, using standard HTTP verbs such as GET, POST, PUT, and DELETE.
- Automatic RESTful API over MongoDB collections: Out-of-the-box support to expose MongoDB documents as REST resources without additional coding.
- Secure authentication and role-based access control: RESTHeart supports authentication using Basic Auth and JWT, and allows you to define fine-grained access policies with its built-in security framework.
- WebSockets and HAL support: Supports WebSocket-based change streams for real-time updates, and provides HAL (Hypertext Application Language) for HATEOAS-compliant APIs.
- Support for JSON and BSON formats: Native support for both formats allows developers to choose the best format for performance and compatibility with MongoDB.
- Custom plugins for extensibility: You can create your own Java-based plugins to intercept requests/responses or add custom logic using the plugin architecture.
- Reactive and non-blocking server: Built using Undertow and Reactive Streams, RESTHeart is designed for high-throughput, non-blocking I/O processing, making it suitable for real-time applications and microservice workloads.
2. Setup
Before getting started with RESTHeart, you need to have both MongoDB and RESTHeart services up and running. The easiest way to do this is by using Docker Compose, which automates the configuration of multi-container applications. This setup runs two services:
- MongoDB: the database where documents and collections are stored
- RESTHeart: the Java-based API layer that exposes MongoDB via RESTful endpoints
You’ll need to have Docker and Docker Compose installed on your system. To spin up the containers, create a file named docker-compose.yml and paste the following content:
version: '3.8'
services:
mongodb:
image: mongo:6.0
container_name: mongodb
ports:
- "27017:27017"
volumes:
- mongo-data:/data/db
restheart:
image: softinstigate/restheart:latest
container_name: restheart
ports:
- "8080:8080"
depends_on:
- mongodb
environment:
- MONGO_URI=mongodb://mongodb:27017
command: ["java", "-Dmongodb.connection-string=mongodb://mongodb:27017", "-jar", "/restheart.jar"]
volumes:
mongo-data:
After saving the file, run the following command in your terminal:
docker-compose up -d
Once the containers are running:
- Access the RESTHeart API via http://localhost:8080
- Access the MongoDB instance on port
27017
To verify everything is working, try listing available collections:
curl http://localhost:8080/
You should receive a JSON response showing available database collections. This confirms that RESTHeart is successfully acting as a REST layer for MongoDB.
3. CRUD Operations with RESTHeart
RESTHeart enables developers to perform full CRUD (Create, Read, Update, Delete) operations over MongoDB collections using standard HTTP methods. These operations map naturally to RESTful conventions and require no additional backend coding. This makes RESTHeart ideal for building data-centric APIs with minimal setup.
RESTHeart supports the following operations using simple HTTP requests:
POSTfor creating new documentsGETfor retrieving documentsPATCHorPUTfor updating existing documentsDELETEfor deleting documents
All endpoints follow the structure: http://localhost:8080/<database>/<collection>/[document-id]
3.1 Insert a Document (Create)
Use the POST method to insert a new document into a collection. This example creates a new user document in the users collection inside the mydb database.
curl -X POST http://localhost:8080/mydb/users \
-H "Content-Type: application/json" \
-d '{"name":"John Doe", "email":"john@example.com"}'
A successful creation returns the HTTP status 201 Created and includes the URI of the newly created resource in the Location header.
HTTP/1.1 201 Created Location: /mydb/users/60f7d2dabc1234
3.2 Read a Document
To retrieve a document, use the GET method with the document’s ID.
curl http://localhost:8080/mydb/users/60f7d2dabc1234
The response includes the full document content, including its MongoDB-generated _id.
{
"_id": "60f7d2dabc1234",
"name": "John Doe",
"email": "john@example.com"
}
3.3 Update a Document
Use the PATCH method to update specific fields of a document without replacing the entire content.
curl -X PATCH http://localhost:8080/mydb/users/60f7d2dabc1234 \
-H "Content-Type: application/json" \
-d '{"email": "newemail@example.com"}'
A successful update returns the HTTP status 200 OK.
HTTP/1.1 200 OK
You can also use PUT to replace the entire document if needed.
3.4 Delete a Document
To remove a document, use the DELETE method with the resource’s URI.
curl -X DELETE http://localhost:8080/mydb/users/60f7d2dabc1234
The response returns HTTP status 204 No Content indicating successful deletion without a response body.
HTTP/1.1 204 No Content
These RESTful endpoints make RESTHeart a powerful abstraction layer for direct interaction with MongoDB, reducing boilerplate and simplifying development.
4. Authentication and Users
RESTHeart supports various authentication mechanisms out of the box. By default, it uses Basic Authentication, but it can be extended to support more secure methods like JWT (JSON Web Tokens) and OAuth 2.0.
4.1 Create a New User
User credentials in RESTHeart are stored in a special MongoDB database called _users. To create a new user, you need to authenticate with an existing admin account and post the user’s credentials and roles.
curl -X POST http://localhost:8080/_users \
-u admin:secret \
-H "Content-Type: application/json" \
-d '{
"_id": "john",
"password": "pass123",
"roles": ["data-reader", "data-writer"]
}'
The above command registers a new user john with the roles data-reader and data-writer. These roles determine the user’s level of access to specific resources.
4.2 Enable Authentication
To enforce authentication, you must enable it in the restheart.yml configuration file. This file allows you to configure security settings, specify the user database, and choose the authentication mechanism.
security: enabled: true usersDatabase: _users authenticationMechanism: BASIC
Once the configuration is updated, restart the RESTHeart server to apply the changes (Make a note that you can either manually restart by logging into the Docker container or simply restart the container directly.).
./bin/restheart
4.2.1 Access with Authenticated User
After enabling authentication, you must use valid credentials to access secured endpoints. Below is an example using the john user to read data from the users collection.
curl -u john:pass123 http://localhost:8080/mydb/users
The successful response confirms that the authenticated user has permission to access the requested resource. You can define additional roles and fine-grained access control by modifying the users documents or using the built-in access management features provided by RESTHeart.
[
{
"_id": "60f7d2dabc1234",
"name": "John Doe",
"email": "newemail@example.com"
}
]
5. Conclusion
RESTHeart offers a powerful and flexible way to expose MongoDB as a RESTful API with minimal setup. Its support for secure authentication, role-based access, and high-performance architecture makes it an excellent choice for rapid development of backend services. Whether you’re building microservices or full-fledged applications, RESTHeart can save you significant development time.
