v9 (current) v8
Edit Page

Plugin Development Overview RESTHeart

What Are Plugins?

RESTHeart is ready to go as soon as you install and configure it, with comprehensive MongoDB API and security functionality built-in. For many standard web applications, these basic features are sufficient.

These functionalities are provided by standard plugins distributed with RESTHeart in the ./plugins directory:

plugins
├── lib/                         # Plugin dependencies
├── restheart-graphql.jar       # GraphQL API
├── restheart-metrics.jar       # Metrics and monitoring
├── restheart-mongoclient-provider.jar  # MongoDB connection
├── restheart-mongodb.jar        # REST API for MongoDB
├── restheart-polyglot.jar       # JavaScript/TypeScript support
└── restheart-security.jar       # Authentication & Authorization

Developing custom plugins is how you extend RESTHeart with your own business logic. You can develop plugins in Java, Kotlin, or JavaScript.

Plugin Types

RESTHeart supports 4 types of plugins, each serving a specific purpose:

Type Purpose Example Use Cases

Services

Add web endpoints to handle HTTP requests

REST APIs, GraphQL endpoints, file uploads, custom business logic

Interceptors

Monitor and modify requests/responses at different lifecycle stages

Logging, validation, data transformation, adding headers

Initializers

Execute initialization logic at startup

Database setup, loading reference data, starting background tasks

Providers

Supply objects to other plugins via dependency injection

Database connections, shared utilities, configuration objects
Tip
 You can also extend the security layer with specialized security plugins. See Authentication Mechanisms, Authenticators, Authorizers, and Token Managers.

Learning Path

We recommend learning plugin development in this order:

  1. Start here: Plugin Development Tutorial - Build your first plugin step-by-step

  2. Understand the basics: This page (you are here) - Core concepts and setup

  3. Deep dive by type:

  4. Deploy: Deploy Plugins - Package and deploy your plugins

  5. Advanced: JavaScript Plugins - Use JavaScript/TypeScript

Quick Start: Plugin Skeleton

The fastest way to start is with our plugin skeleton project:

$ git clone --depth 1 git@github.com:SoftInstigate/restheart-plugin-skeleton.git
$ cd restheart-plugin-skeleton
$ ./mvnw clean package
$ docker run --rm -p 8080:8080 -v ./target:/opt/restheart/plugins/custom softinstigate/restheart -s

Test the example service:

$ curl localhost:8080/srv
{"message":"Hello World!","rnd":"njXZksfKFW"}
Tip
 Check the skeleton repository README and browse the official plugin examples for more code samples.

Understanding Plugin Development

Before diving into building plugins, you should understand some core concepts:

Essential concepts (recommended for all developers):

  • @RegisterPlugin annotation - How RESTHeart discovers and configures your plugin

  • Configuration - How to configure plugins via restheart.yml

  • Dependency Injection - How to access MongoDB, configuration, and other services

  • Request/Response Types - Understanding type safety and content handling

➡️ Read: Plugin Core Concepts

When you’re ready to code:

Next Steps

Now that you understand the basics, follow this learning path:

  1. Understand the concepts: Core Concepts - Essential knowledge before coding

  2. Hands-on practice: Complete the Plugin Development Tutorial to build your first working plugin

  3. Learn each plugin type:

  4. Deploy your plugins: Deployment Guide

  5. Explore examples: Browse official examples on GitHub

Reference

The only required dependency to develop a plugin is restheart-commons.

With maven: