REST API

The REST API exposes a read-only view of an EclipseStore Storage instance. It is intended for inspection, monitoring, and tooling — not as a query language. All endpoints are HTTP GET and return application/json by default.

Base URL and instance name

Every endpoint is mounted below a base URL whose shape depends on the chosen service implementation (see Setup):

Implementation Default base URL

Implementation	Default base URL
Javalin (recommended for standalone applications)	`http://<host>:4567/store-data`
Spring Boot (recommended for Spring Boot applications)	`http://<host>:<port>/store-data/<storage-name>`

Javalin (recommended for standalone applications)

http://<host>:4567/store-data

Spring Boot (recommended for Spring Boot applications)

http://<host>:<port>/store-data/<storage-name>

In the route tables below, [instance-name] is the placeholder for the storage instance segment of the URL.

For Javalin, this is a single configurable name (store-data by default; see Setup for the environment variables that override the port and name).
For Spring Boot, this is the bean name of the storage manager, or default when the auto-configured manager is used. Multiple storage managers are exposed side by side under their respective bean names.

All numeric objectId and length fields are emitted as JSON strings, not JSON numbers, to preserve full 64-bit precision in JavaScript clients.

Endpoint overview

Method Route Purpose

Method	Route	Purpose
`GET`	`/`	List all available routes of the service.
`GET`	`[instance-name]/root`	Return name and object id of the storage root.
`GET`	`[instance-name]/object/{objectId}`	Return type information and member values of a single object.
`GET`	`[instance-name]/dictionary`	Return the persistent type dictionary.
`GET`	`[instance-name]/maintenance/filesStatistics`	Return statistics of storage files and channels.

GET

/

List all available routes of the service.

GET

[instance-name]/root

Return name and object id of the storage root.

GET

[instance-name]/object/{objectId}

Return type information and member values of a single object.

GET

[instance-name]/dictionary

Return the persistent type dictionary.

GET

[instance-name]/maintenance/filesStatistics

Return statistics of storage files and channels.

GET Routes

Returns the list of all routes registered by the service. Useful for discovering the available endpoints at runtime.

Response

[
  { "url": "/store-data/default/",                            "httpMethod": "get" },
  { "url": "/store-data/default/root",                        "httpMethod": "get" },
  { "url": "/store-data/default/dictionary",                  "httpMethod": "get" },
  { "url": "/store-data/default/object/:oid",                 "httpMethod": "get" },
  { "url": "/store-data/default/maintenance/filesStatistics", "httpMethod": "get" }
]

GET Root

[instance-name]/root

Returns the name and object id of the storage root element. The returned objectId is the entry point for traversing the object graph through the GET Object endpoint.

Response

{
    "name": "ROOT",
    "objectId": "1000000000000000028"
}

Response fields
Field	Type	Description
name	string	The registered name of the root object (e.g. `ROOT` for the default root).
objectId	string	The object id of the root object.

GET Object

[instance-name]/object/{objectId}

Returns the description and values of a single persisted object identified by its object id. The response contains type information together with the object’s fixed-size and variable-size members.

For container-like objects (collections, arrays, maps, …) the response can be paginated using the fixedOffset, fixedLength, variableOffset, and variableLength query parameters. For value-bearing members (e.g. long strings or byte arrays) the size of each emitted value can be capped via valueLength.

Path parameters
Parameter	Type	Description
objectId	long	The requested object’s id.

Query parameters
Parameter	Type	Description	Default
valueLength	long	Maximum length of each emitted value. Applies to variable-length values such as `String`, `byte[]`, and `char[]`. Values longer than this limit are truncated in the response.	unlimited
fixedOffset	long	Index of the first fixed-size member to include in the response.	0
fixedLength	long	Maximum number of fixed-size members to return, starting at `fixedOffset`.	unlimited
variableOffset	long	Index of the first element to include for each variable-size member (e.g. the entries of a list).	0
variableLength	long	Maximum number of elements to return for each variable-size member, starting at `variableOffset`.	unlimited
references	boolean	If `true`, top-level references of the object are resolved and included in the `references` array of the response.	false
format	string	Requested response format. Currently `json` (alias `application/json`) is supported.	json

Response

{
    "objectId": "1000000000000000028",
    "typeId": "110",
    "length": "0",
    "variableLength": [
        "3"
    ],
    "simplified": false,
    "data": [
        [
            "1000000000000000029",
            "1000000000000000030",
            "1000000000000000031"
        ]
    ],
    "references": null
}

Response fields
Field	Type	Description
objectId	string	Object id of the described object.
typeId	string	Type id of the object. Resolves against the type dictionary.
length	string	Number of fixed-size members of the object as defined by its type. `0` if the type has no fixed-size members.
variableLength	string[]	For each variable-size member, the total number of elements available — independent of `variableOffset` / `variableLength`. Use this to drive pagination.
simplified	boolean	`true` for primitive wrapper objects whose value is reported in `data` directly instead of as a member array. `false` for ordinary objects.
data	array	The collected members. Fixed-size members are emitted first, in declared order, followed by variable-size members. Each variable-size member is itself a JSON array. References to other persisted objects are emitted as their object id (string).
references	array	`null` unless `references=true` was requested. When present, contains a fully nested object description for every top-level reference held by the object, using the same shape as this response.

Pagination example

[instance-name]/object/1000000000000000028?variableOffset=100&variableLength=50

Returns elements 100..149 of each variable-size member of the object.

GET Type Dictionary

[instance-name]/dictionary

Returns the persistent type dictionary of the storage as plain text. The dictionary maps type ids (as returned in the typeId field of object descriptions) to fully qualified Java type names and their persisted member layout.

The response is the textual representation produced by the underlying serializer and is intended to be consumed by tooling rather than parsed ad hoc.

Response (excerpt)

1:java.lang.Object
{
}

110:java.util.ArrayList
{
    int                                            size            ;
    [java.lang.Object]                             elementData     ;
}

GET Files Statistics

[instance-name]/maintenance/filesStatistics

Returns statistics about the storage’s data files broken down per channel. Use this endpoint to monitor storage size, channel balance, and the ratio of live to total data.

Response

{
    "creationTime": "2020-04-15T13:32:26.003Z",
    "channelStatistics": {
        "0": {
            "channelIndex": 0,
            "files": [
                {
                    "fileNumber": "1",
                    "file": "storage/channel_0/channel_0_1.dat",
                    "fileCount": "1",
                    "liveDataLength": "2898",
                    "totalDataLength": "2930"
                }
            ],
            "fileCount": "1",
            "liveDataLength": "2898",
            "totalDataLength": "2930"
        }
    },
    "fileCount": "1",
    "liveDataLength": "2898",
    "totalDataLength": "2930"
}

Top-level fields
Field	Type	Description
creationTime	string (ISO-8601)	Time at which the statistics were computed.
channelStatistics	object	Map of channel index (as string) to the statistics of that channel.
fileCount	string	Total number of data files across all channels.
liveDataLength	string	Sum of live (still referenced) data bytes across all channels.
totalDataLength	string	Sum of total data bytes (live + garbage) across all channels.

Per-channel and per-file fields
Field	Type	Description
channelIndex	number	Zero-based index of the channel.
files	array	Per-file statistics for this channel.
fileNumber	string	Sequence number of the data file within its channel.
file	string	Storage-relative path of the data file.
liveDataLength	string	Live data bytes in this file.
totalDataLength	string	Total data bytes in this file (live + garbage). The difference between `totalDataLength` and `liveDataLength` represents space that can be reclaimed by housekeeping.

Error responses

All endpoints return HTTP 404 Not Found with a plain-text body when:

a path or query parameter has an invalid type (e.g. a non-numeric objectId, a negative offset / length, or an unsupported format),
the requested object id does not exist,
the requested storage name is not registered (Spring Boot only — multiple storage managers are addressed by bean name).

The body of the response contains a short human-readable description of the failing parameter or condition.