This repository provides a skeleton project for RESTHeart Plugins.
Documentation for plugins development is available at https://restheart.org/docs/plugins/overview/.
Check also the RESTHeart Greetings Services Tutorial
- Java 21+ (or GraalVM 21+)
- Docker
$ git clone --depth 1 git@github.com:SoftInstigate/restheart-plugin-skeleton.git && cd restheart-plugin-skeleton
$ ./mvnw clean package && docker run --name restheart --rm -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart -s
The -s
option (standalone mode) disables the plugins depending on MongoDB; this avoids to start MongoDB for running it.
The project skeleton defines a dummy Service bound at /srv
:
With curl
$ curl localhost:8080/srv
{"message":"Hello World!","rnd":"njXZksfKFW"}%
with httpie
$ http -b :8080/srv
{
"message": "Hello World!",
"rnd": "KvQGBwsPBp"
}
WARNING: This setup is insecure and should be only used for developing or testing purposes.
This setup only needs to be completed once. Follow these steps:
- Launch a MongoDB container:
$ docker run -d --name mongodb -p 27017:27017 mongo --replSet=rs0
- Initialize MongoDB as a Single Node Replica Set
$ docker exec mongodb mongosh --quiet --eval "rs.initiate()"
- Build and Launch RESTHeart Container
$ ./mvnw clean package && docker run --name restheart --rm -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart
NOTE: we don't specify the -s
option, so RESTHeart connects to MongoDB and provides the Data APIs.
Test a simple GET /users request. The admin
user is created automatically.
With curl
$ curl -u admin:secret localhost:8080/users
[{"_id": "admin", "roles": ["admin"]}]%
With httpie:
$ http -a admin:secret :8080/users
You might want to check the REST API Tutorial and the GraphQL Tutorial
The script docker/docker-entrypoint-initdb.d/initdb.js
is executed by the mongo shell in the MongoDB container and allows initializing MongoDB, for instance creating test data.
The default configuration is used. The environment variable RHO
can be used to override the configuration. See Change the configuration in Docker container
Here an example to define the dummy Service message:
$ docker run --name restheart --rm -e RHO="/http-listener/host->'0.0.0.0';/mclient/connection-string->'mongodb://host.docker.internal';/helloWorldService/message->'Ciao Mondo!'" -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart -s
Here we override the configuration option /helloWorldService/message
with Ciao Mondo!
. The other overrides are needed: when defining your RHO variable always set /http-listener/host→"0.0.0.0"
and your /mclient/connection-string
.
$ curl localhost:8080/srv
{"message":"Ciao Mondo!","rnd":"rhyXFHOQUA"}%
The dependencies jars are copied by the maven-dependency-plugin
to the target/lib
directory. Those jars are copied to the RESTHeart's plugins
directory to add them to to the classpath by the script bin/restart.sh
.
When you add a dependency, you must restart the RESTHeart container.
restheart.jar
embeds several jars. You should avoid adding to the classpath a jar that is already included in it.
You can avoid a dependency to be added to the classpath by specifying the scope provided
in the pom dependency. For instance, the restheart-commons
dependency has the scope provided
because it is already embedded in restheart.jar
:
<dependency>
<groupId>org.restheart</groupId>
<artifactId>restheart-commons</artifactId>
<version>8.0</version>
<scope>provided</scope>
</dependency>
Other libraries that are embedded in restheart.jar
are the MongoDB driver and Unirest http library.
You can check which libraries are embedded in restheart.jar
as follows:
$ git clone https://github.com/SoftInstigate/restheart.git && cd restheart
$ mvn dependency:tree -Dscope=compile
The jar filename, is defined in pom.xml
as equal to the artifactId.
<artifactId>restheart-plugin-skeleton</artifactId>
...
<build>
<finalName>${project.artifactId}</finalName>
...
</build>
RESTHeart supports native images builds with GraalVM.
See Deploy Java Plugins on RESTHeart native documentation page for more information.
Building RESTHeart with your plugin as a native image requires the GraalVM and its native-image
tool.
We suggest to install GraalVM with sdk
$ sdk install java 21.0.3-graal
The pom.xml
defines the native
profile. To build your RESTHeart embedding your plugin run:
$ ./mvnw clean package -Pnative
NOTE: native image build takes few minutes!
The binary executable is ./target/restheart-plugin-skeleton
Run it with:
$ RHO="/fullAuthorizer/enabled->true" target/restheart-plugin-skeleton
NOTE: The native image is configured to build with custom plugins and the restheart
and restheart-polyglot
modules. The default RESTHeart plugins (restheart-security
, restheart-mongodb
, restheart-graphql
, and restheart-mongoclient-provider
) are currently commented out in the pom.xml
. To include these plugins in the native image, simply uncomment their dependencies in the native
profile section of the pom.xml
.
The RHO
environment variable enables the fullAuthorizer
. Since restheart-security
is excluded by default from this native image, any requests are authorized by default when this variable is set.
The code includes a super simple "Hello World" service. You can test it as follows:
httpie
$ http :8080/srv
{
"msg": "Hello World!"
}
curl
$ curl localhost:8080/srv
{"message":"Hello World!sss ss","rnd":"njXZksfKFW"}%%
HTTP Shell
HTTP Shell provides developers with a modern alternative to HTTP clients for interacting with APIs.
download HTTP Shell from GitHub
> h set url :8080
> h get /srv