Setup

See Best Practices: Dev / Test / Prod for environment-specific recommendations on exposing the REST interface in production.

An application that will expose the REST endpoints needs one of the provided implementations by EclipseStore or you need to implement the provided interfaces.

Currently, two implementations are available:

  • Javalin REST Service — recommended for standalone applications.

  • Spring Boot 3.x REST Service — recommended for Spring Boot applications.

Spring Boot REST Service

In this example, we will use Spring Boot implementation that EclipseStore provides. This requires a fully functional Spring Boot 3 with Spring Web MVC already set-up and configured. If you are unsure how to do so, please consult the original SpringBoot documentation.

Please add the following dependencies to your project:

pom.xml
<dependencies>
    <dependency>
      <groupId>org.eclipse.store</groupId>
      <artifactId>storage-restservice-springboot</artifactId>
      <version>4.3.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>${spring-boot.version}</version>
    </dependency>
</dependencies>

Using your preferred configuration format, please activate the REST service in your configuration. For example using properties file the configuration looks like:

application.properties
org.eclipse.store.rest.enabled=true

This is it. This configuration will provide an additional REST endpoint accessible via /store-data/ providing information about your store. If your application starts a web server on port 8080, and you haven’t changed the default configuration, the complete base URL will be http://localhost:8080/store-data/. Open it a browser to see further available URLs provided by the REST service.

The REST controller is able to provide information about multiple Storage managers of your system. For a storage manager called some its details are available via /storage-data/some. If you haven’t changed the storage manager configuration and use the default one provided by the SpringBoot integration, it will be available via /storage-data/default.

Additional Configuration

You might want to change the base URL of your service. This is possible using the configuration file of your SpringBoot application. The corresponding property is org.eclipse.store.rest.base-url. The example below changes the base URL to /some/other/location:

application.properties
org.eclipse.store.rest.base-url=/some/other/location

Javalin Java REST Service

In this example, we will use the Javalin implementation that EclipseStore provides.

pom.xml
<dependencies>
    <dependency>
        <groupId>org.eclipse.store</groupId>
        <artifactId>storage-restservice-javalin</artifactId>
        <version>4.3.0</version>
    </dependency>
</dependencies>

Additional Configuration

If you want to change the default port (4567) or instance name (store-data) it can be done by using the program variables:

Table 1. Javalin REST Service - environment variables
Environment variable Default value Description

eclipse_store_rest_port

4567

TCP port of the REST service (valid range 1–65535).

eclipse_store_rest_storage_name

store-data

Instance name used in the base URL (without leading/trailing "/").

eclipse_store_rest_ui_enabled

false

Serve the bundled Storage Viewer web UI from the REST service. See below.

Bundled Storage Viewer (Web UI)

The Javalin REST service ships with a small, dependency-free (Vanilla-JS) web viewer. It is disabled by default. Enable it by setting the eclipse_store_rest_ui_enabled flag to true, e.g. as a JVM system property:

java -Declipse_store_rest_ui_enabled=true -cp ... your.Main

When enabled, the viewer is served from the root path of the same port as the REST service. Because the UI and the REST API share the same origin, no CORS configuration or reverse proxy is required. Open http://localhost:4567/ in your browser and enter the base URL of the REST service (http://localhost:4567/store-data) to connect.

See Client GUI for details.