Transport & REST API

The Trove extension exposes a full REST API for object storage operations. All endpoints are registered under the configured base path (default: /trove/v1).

Endpoints01

Buckets

Method	Path	Description
`POST`	`/buckets`	Create a bucket
`GET`	`/buckets`	List all buckets
`GET`	`/buckets/:bucket`	Get bucket info
`DELETE`	`/buckets/:bucket`	Delete a bucket

Objects

Method	Path	Description
`PUT`	`/buckets/:bucket/objects/*key`	Upload an object
`GET`	`/buckets/:bucket/objects/*key`	Download an object
`DELETE`	`/buckets/:bucket/objects/*key`	Delete an object
`HEAD`	`/buckets/:bucket/objects/*key`	Get object metadata
`GET`	`/buckets/:bucket/objects`	List objects in a bucket

Multipart Uploads

Method	Path	Description
`POST`	`/buckets/:bucket/uploads`	Initiate multipart upload
`PUT`	`/buckets/:bucket/uploads/:id/parts/:partNum`	Upload a part
`POST`	`/buckets/:bucket/uploads/:id/complete`	Complete upload
`DELETE`	`/buckets/:bucket/uploads/:id`	Abort upload
`GET`	`/buckets/:bucket/uploads/:id`	Get upload status

Content-Addressable Storage

Method	Path	Description
`PUT`	`/cas`	Store content by hash
`GET`	`/cas/:hash`	Retrieve content by hash
`HEAD`	`/cas/:hash`	Check if hash exists

Admin

Method	Path	Description
`GET`	`/admin/stats`	Storage statistics

Request / Response Examples02

Upload an Object

curl -X PUT \
  http://localhost:8080/trove/v1/buckets/uploads/objects/photos/cat.jpg \
  -H "Content-Type: image/jpeg" \
  --data-binary @cat.jpg

{
  "bucket": "uploads",
  "key": "photos/cat.jpg",
  "size": 204800,
  "content_type": "image/jpeg",
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
  "last_modified": "2025-01-15T10:30:00Z"
}

Download an Object

curl http://localhost:8080/trove/v1/buckets/uploads/objects/photos/cat.jpg \
  -o cat.jpg

The response streams the object body with appropriate Content-Type, Content-Length, and ETag headers.

List Objects

curl "http://localhost:8080/trove/v1/buckets/uploads/objects?prefix=photos/&limit=100"

{
  "objects": [
    {
      "key": "photos/cat.jpg",
      "size": 204800,
      "last_modified": "2025-01-15T10:30:00Z"
    }
  ],
  "truncated": false
}

CAS Store

curl -X PUT \
  http://localhost:8080/trove/v1/cas \
  -H "Content-Type: application/octet-stream" \
  --data-binary @data.bin

{
  "hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "size": 1024,
  "deduplicated": false
}

Headers03

Request Headers

Header	Description
`Content-Type`	MIME type for uploads
`Content-Length`	Object size (optional, enables size validation)
`X-Trove-Checksum`	Expected checksum for integrity verification
`X-Subject-ID`	Subject identifier for authorization (set by auth middleware)

Response Headers

Header	Description
`ETag`	Object entity tag
`Content-Type`	Object MIME type
`Content-Length`	Object size in bytes
`Last-Modified`	Object modification timestamp
`X-Trove-Checksum`	Server-computed checksum

Error Responses04

All errors follow a consistent JSON format:

{
  "error": "object not found",
  "code": 404
}

Code	Meaning
`400`	Bad request (missing bucket, invalid key)
`403`	Forbidden (Warden denied access)
`404`	Object, bucket, or upload not found
`409`	Conflict (bucket already exists)
`413`	Payload too large (quota exceeded)
`500`	Internal server error

← Previous

Configuration

Grove Store Layer