REST API

LoomCache ships two REST surfaces:

1. Built into every node — served by RestApiServer + RestApiRouter under /api/v1/* with a management dashboard at /dashboard.
2. Spring Boot starter — controllers in loom-spring-boot/.../controller under /api/*.

Both validate inputs and return JSON.

Server-side router (/api/v1)

Base URL: http://<node>:<rest-port>/api/v1. RestApiServer binds the port chosen at node startup.

Maps

Method	Path	Description
GET	/maps/{mapName}	List keys / entries.
GET	/maps/{mapName}/{key}	Get value.
PUT	/maps/{mapName}/{key}	Put JSON body.
DELETE	/maps/{mapName}/{key}	Delete key.
POST	/maps/{mapName}/query	SQL-like query body.

Queues

Method	Path	Description
POST	/queues/{queueName}/offer	Enqueue element.
POST	/queues/{queueName}/poll	Dequeue head.
GET	/queues/{queueName}/size	Current size.

Sets

Method	Path	Description
POST	/sets/{setName}/add	Add element.
GET	/sets/{setName}/members	List members.
DELETE	/sets/{setName}/{element}	Remove element.

Topics

Method	Path	Description
POST	/topics/{topicName}/publish	Publish JSON body.
GET	/topics/{topicName}/subscribe	Subscribe through the current polling-backed topic endpoint.

Cluster

Method	Path	Description
GET	/cluster/info	Full cluster snapshot.
GET	/cluster/members	Known members + their phi scores.
GET	/cluster/health	Aggregate health status.

Management dashboard

• GET /dashboard — bundled HTML dashboard.
• GET /api/v1/management/... — JSON endpoints that back the dashboard.

Spring Boot starter (/api)

loom-spring-boot/.../controller:

Controller	Base path	Verbs
MapController	/api/map	GET /{key}, PUT /{key}, DELETE /{key}, GET /, GET /size, DELETE /
QueueController	/api/queue	POST /, POST /poll, GET /peek, GET /size, POST /drain
SetController	/api/set	POST /, GET /members/{element}, DELETE /members/{element}, GET /, GET /size, DELETE /
TopicController	/api/topic	POST /, GET /stats
QueryController	/api/query	POST /
ClusterController	/api/cluster	GET /status, GET /members, GET /health, POST /raft/step-down, GET /cp-subsystem/groups, GET /cp-subsystem/sessions, POST /cp-subsystem/sessions/{sessionId}/force-close
LockController	/api/lock	POST /acquire, POST /release, GET /
AtomicController	/api/atomic	GET /long, PUT /long, POST /long/add, POST /long/increment, POST /long/decrement, POST /long/cas, GET /reference, PUT /reference, DELETE /reference, POST /reference/cas
MultiMapController	/api/multimap	POST /{key}, GET /{key}, DELETE /{key}/values, DELETE /{key}, GET /, GET /keys, GET /size
ListController	/api/list	POST /, POST /{index}, GET /{index}, PUT /{index}, DELETE /{index}, GET /, GET /size, DELETE /
RingbufferController	/api/ringbuffer	POST /, GET /{sequence}, GET /, GET /status, DELETE /
ReliableTopicController	/api/topic-reliable	POST /, GET /, GET /stats
CounterController	/api/counter	GET /, POST /increment, POST /decrement

All inputs are validated by InputValidator and @Valid — invalid payloads return 400 Bad Request with a JSON error body.

OpenAPI

The Spring Boot starter publishes an OpenAPI document for the /api/** controller group at GET /v3/api-docs/loomcache-api. The endpoint is generated by springdoc-openapi-starter-webmvc-api and is public so operators can pull the spec for client generation or gateway validation before applying API credentials.

Ops CLI

The loom-cli module packages com.loomcache.cli.LoomCli with a manifest main class. It talks to the same HTTP surfaces:

export LOOM_URL=https://node-1:8080
export LOOM_ADMIN_USER="${LOOM_ADMIN_USER:?set}"
export LOOM_ADMIN_PASSWORD="${LOOM_ADMIN_PASSWORD:?set}"
java -jar loom-cli/target/loom-cli-1.0.0-SNAPSHOT.jar cluster state
java -jar loom-cli/target/loom-cli-1.0.0-SNAPSHOT.jar data-structures list
java -jar loom-cli/target/loom-cli-1.0.0-SNAPSHOT.jar data-structures inspect --type map --name default --page 0 --size 50
java -jar loom-cli/target/loom-cli-1.0.0-SNAPSHOT.jar --basic "${LOOM_ADMIN_USER}:${LOOM_ADMIN_PASSWORD}" force-leader-step-down
java -jar loom-cli/target/loom-cli-1.0.0-SNAPSHOT.jar --basic "${LOOM_ADMIN_USER}:${LOOM_ADMIN_PASSWORD}" cp-admin list-groups
java -jar loom-cli/target/loom-cli-1.0.0-SNAPSHOT.jar --basic "${LOOM_ADMIN_USER}:${LOOM_ADMIN_PASSWORD}" cp-admin list-sessions
java -jar loom-cli/target/loom-cli-1.0.0-SNAPSHOT.jar --basic "${LOOM_ADMIN_USER}:${LOOM_ADMIN_PASSWORD}" cp-admin force-close-session --session-id session-123
java -jar loom-cli/target/loom-cli-1.0.0-SNAPSHOT.jar raft-log export --input wal-node-1.log --output export.jsonl --format json
java -jar loom-cli/target/loom-cli-1.0.0-SNAPSHOT.jar raft-log export --input wal-node-1.log --output typed-wal.log --format typed-wal --from-index 100

force-leader-step-down and cp-admin write commands call ADMIN-gated Spring endpoints; the read-only data-structure commands use the management JSON endpoints that back /dashboard. raft-log export is local-only: it strictly validates the input WAL and writes either JSONL metadata or a typed WAL copy for log-format migration.

Correlation IDs

The server extracts an incoming X-Correlation-ID (or X-Request-ID) and echoes it on the response. If neither is present, it generates one. Use the same header to correlate traces across gateway → LoomCache.

Authentication

The built-in node router (/api/v1/**) uses AuthConfig:

• Bearer-token / JWT is not handled natively — put an authenticating reverse proxy in front.
• The proxy must forward X-Auth-User + X-Auth-Roles; the server trusts them only if the mTLS peer matches one of authConfig.trustedGatewayAddresses.

For CN-based permissions, present an mTLS client certificate whose Common Name matches a configured authConfig.certPermissions pattern — see Security & mTLS.

The Spring Boot starter uses Spring Security for /api/** and /token. HTTP Basic and mTLS-authenticated callers can request a short-lived JWT from POST /token when loomcache.security.jwt.enabled=true and loomcache.security.jwt.signing-secret is at least 32 bytes. The default token TTL is 15 minutes. Bearer-token validation for protected Spring REST resources is still intended to live at a gateway or application security layer.

Errors

HTTP	Body
400	{ "error": "Bad Request", "message": "..." }
404	{ "error": "Not Found", "message": "..." }
405	{ "error": "Method Not Allowed", "message": "Allowed: ..." }
500	{ "error": "Internal Server Error", "message": "..." }