RESTHeart

The Backend Framework with MongoDB Data APIs.

---

What is RESTHeart?

RESTHeart instantly exposes the full power of MongoDB through REST, GraphQL, and WebSocket APIs with zero coding required.

Available as a Docker image and optimized for GraalVM native compilation, RESTHeart delivers instant startup time and a minimal memory footprint. With native binary images available for Linux, Windows, and macOS.

A built-in, battle-tested security layer keeps your application protected out of the box, handling authentication and authorization without writing a single line of security code.

Extend RESTHeart with a lightweight plugin framework that makes it easy to build microservices in Java, Kotlin, JavaScript, or TypeScript, using four simple building blocks: Service, Provider, Interceptor, and Initializer.

Built on modern Java 25 and Undertow, the high-performance HTTP server powering WildFly, with proven production deployments at enterprise scale.

Core capabilities:

• REST API — Full CRUD, aggregations, filtering, sorting, pagination
• GraphQL — Define schemas and map them to MongoDB queries
• WebSocket — Real-time change streams and data sync
• Authentication & Authorization — JWT, OAuth2, LDAP, MongoDB-based users, ACL rules
• Plugin system — Extend with Java, JavaScript, or Python when you need custom logic

No code required for standard database operations. Write plugins only for custom business logic.

---

Quick Start

# Start MongoDB + RESTHeart with Docker Compose
curl https://raw.githubusercontent.com/SoftInstigate/restheart/master/docker-compose.yml \
  --output docker-compose.yml && docker compose up --attach restheart

# Test it
curl http://localhost:8080/ping

Default credentials: admin / secret (change in production)

More options: https://restheart.org/docs/foundations/quick-start

---

Example: Query MongoDB via HTTP

const url = encodeURI('https://demo.restheart.org/messages?filter={"from":"Bob"}&pagesize=1');

fetch(url)
  .then(response => response.json())
  .then(json => console.log(JSON.stringify(json, null, 2)));

That's it. No Express routes, no Mongoose schemas, no middleware setup.

📄 Full documentation: https://restheart.org/docs/

---

Architecture

RESTHeart sits between clients and MongoDB, providing:

• API layer — REST, GraphQL, WebSocket endpoints
• Security — Authentication, authorization, request validation
• Plugin runtime — Custom business logic in Java, JavaScript, or Python
• Observability — Metrics, logging, health checks

---

Key Features

• 🔌 Zero-config API — Collections automatically become REST endpoints
• 🔐 Production-ready security — JWT, OAuth2, LDAP, role-based access control
• ⚡ High performance — Undertow NIO + Java Virtual Threads, handles 10K+ concurrent connections
• 💬 Real-time — Native WebSocket support for MongoDB change streams
• 🧩 Extensible — Plugin system supports Java, JavaScript, TypeScript, Python
• 🚀 Stateless — Scales horizontally, runs on VMs, containers, Kubernetes, or as native binary

Battle-tested: 2M+ downloads, 10+ years in production at scale.

---

Use Cases

• API development without boilerplate — Skip CRUD code, focus on business logic
• Mobile and web backends — Get REST/GraphQL APIs immediately
• Real-time applications — WebSocket support for chat, notifications, live dashboards
• MongoDB Data API replacement — Self-hosted alternative to the deprecated Atlas Data API (migration guide)
• Legacy modernization — Add modern APIs to existing MongoDB databases
• PostgreSQL with MongoDB API — Use via FerretDB for PostgreSQL storage (tutorial)

---

Extend with Plugins

Write custom logic only when you need it. RESTHeart handles the rest.

Java Plugin

@RegisterPlugin(name = "greetings")
public class GreeterService implements JsonService {
    @Override
    public void handle(JsonRequest req, JsonResponse res) {
        res.setContent(object()
            .put("message", "Hello World!")
            .put("timestamp", Instant.now()));
    }
}

JavaScript Plugin

export const options = {
    name: "greetings",
    uri: "/greetings"
}

export function handle(request, response) {
    response.setContent(JSON.stringify({
        message: 'Hello World!',
        timestamp: new Date().toISOString()
    }));
    response.setContentTypeAsJson();
}

Plugin capabilities:

• Services (custom REST endpoints)
• Interceptors (modify requests/responses, add validation)
• Initializers (run code at startup)
• Providers (dependency injection)

📖 Plugin development: https://restheart.org/docs/plugins/overview/

🔧 Use restheart-cli for scaffolding, testing, and hot-reload.

---

Deployment

Docker

docker pull softinstigate/restheart:latest

docker run -p 8080:8080 \
  -v ./restheart.yml:/opt/restheart/etc/restheart.yml \
  softinstigate/restheart

Kubernetes

Stateless architecture supports horizontal scaling. Configure with ConfigMaps and Secrets.

Native Executables

Prebuilt binaries for macOS, Linux, Windows with faster startup and lower memory.

See docs/native-executables.md for download links.

RESTHeart Cloud

Fully managed service: cloud.restheart.com

• Instant provisioning
• Automatic scaling
• Free tier available
• Premium plugins (Webhooks, Sophia AI, Facet)

---

Database Compatibility

Database	Support Level	Notes
✅ MongoDB	Full	All versions 3.6+
✅ MongoDB Atlas	Full	Cloud-native support
✅ Percona Server	Full	Drop-in MongoDB replacement
⚙️ FerretDB	Partial	PostgreSQL-backed (tutorial)
⚙️ AWS DocumentDB	Partial	Most features work
⚙️ Azure Cosmos DB	Partial	MongoDB API compatibility layer

---

Community & Support

• 📄 Documentation — API reference and guides
• 🤖 Ask Sophia — AI documentation assistant
• 💬 Slack — Community chat
• 🐛 GitHub Issues — Bug reports and feature requests
• 💡 Stack Overflow — Tag: restheart

---

Contributing

Contributions welcome. RESTHeart is open source (AGPL).

• Report bugs and request features via GitHub Issues
• Submit pull requests
• Improve documentation
• Share use cases

See CONTRIBUTING.md for guidelines.

---

License

Dual-licensed:

• RESTHeart core is AGPL v3. Plugins you write are yours: the SDK is Apache 2.0, so your custom code stays proprietary.
• Commercial — For proprietary applications. See restheart.com for available options.

---

Built with ❤️ by SoftInstigate | GitHub | Website | Cloud

---