tommy s3 API v1
Accepts S3-compatible bucket and object operations without sending data to cloud storage, and keeps the resulting object catalog available for inspection. Logical bucket and object mutations are also captured as searchable events, while the catalog and its bytes can be kept across restarts with filesystem storage.
These routes read back what tommy captured, in the shape this content type
wants: filters that only mean something here, and the parts that are bytes
rather than JSON. They read from the same store as the events API, so a
client that sends and immediately fetches sees its own write, and every
entry carries the id of the event behind it.
The events API - /api/v1/events, described in its own document - is the
generic view of the same captures, and is the one to use when what you are
asserting does not depend on the content type. The fake vendor endpoints are
described nowhere here: they are the vendors' specifications, not tommy's.
This document is generated from the server's route table. It cannot describe
a route that does not exist, and CI fails if the checked-in copy stops
matching the code.
Server
/api/v1/s3 — This tommy's s3 API.
Operations
GET
/buckets
List current buckets and aggregate S3 catalog statistics.
DELETE
/buckets
Delete every bucket, object, and inactive multipart upload while retaining the event history.
Responses
| Status | Body | Description |
|---|
204 |
no body |
Done. No body. |
GET
/buckets/{bucket}
Get one current bucket snapshot and its object-list link.
Parameters
| Name | In | Type | Description |
|---|
bucket required |
path |
string |
|
Responses
| Status | Body | Description |
|---|
200 |
application/json · s3.BucketView
|
Success. |
404 |
application/json · api.Error
|
No such resource, or it belongs to another plugin. |
DELETE
/buckets/{bucket}
Delete an empty bucket, or all of its state when recursive is true.
Parameters
| Name | In | Type | Description |
|---|
bucket required |
path |
string |
|
recursive |
query |
boolean |
Delete objects and inactive multipart uploads before deleting the bucket. |
Responses
| Status | Body | Description |
|---|
204 |
no body |
Done. No body. |
400 |
application/json · api.Error
|
A query parameter could not be parsed - a malformed since, a negative limit. |
404 |
application/json · api.Error
|
No such resource, or it belongs to another plugin. |
GET
/buckets/{bucket}/content/{key}
Download one object's bytes and recorded representation metadata, with HTTP range support.
Parameters
| Name | In | Type | Description |
|---|
bucket required |
path |
string |
|
key required |
path |
string |
|
Responses
| Status | Body | Description |
|---|
200 |
application/octet-stream
|
Success. |
404 |
application/json · api.Error
|
No such resource, or it belongs to another plugin. |
GET
/buckets/{bucket}/objects
List one bucket with exact S3 prefix, delimiter, continuation, and maximum-key semantics.
Parameters
| Name | In | Type | Description |
|---|
bucket required |
path |
string |
|
prefix |
query |
string |
Only keys beginning with this exact prefix. |
delimiter |
query |
string |
Group keys after the prefix into common prefixes. |
start_after |
query |
string |
Start strictly after this key or common prefix. |
continuation |
query |
string |
Continue strictly after the token returned by the previous page. |
max_keys |
query |
integer |
Maximum objects and common prefixes in this page; capped at 1000. |
Responses
| Status | Body | Description |
|---|
200 |
application/json · s3.ObjectsView
|
Success. |
400 |
application/json · api.Error
|
A query parameter could not be parsed - a malformed since, a negative limit. |
404 |
application/json · api.Error
|
No such resource, or it belongs to another plugin. |
GET
/buckets/{bucket}/objects/{key}
Get metadata for one exact object key, without treating the key as a filesystem path.
Parameters
| Name | In | Type | Description |
|---|
bucket required |
path |
string |
|
key required |
path |
string |
|
Responses
| Status | Body | Description |
|---|
200 |
application/json · s3.ObjectView
|
Success. |
404 |
application/json · api.Error
|
No such resource, or it belongs to another plugin. |
DELETE
/buckets/{bucket}/objects/{key}
Delete one exact object and append an s3.object.delete event.
Parameters
| Name | In | Type | Description |
|---|
bucket required |
path |
string |
|
key required |
path |
string |
|
Responses
| Status | Body | Description |
|---|
204 |
no body |
Done. No body. |
404 |
application/json · api.Error
|
No such resource, or it belongs to another plugin. |
Schemas
api.Error
| Property | Type |
|---|
error required | string |
blob.Ref
| Property | Type |
|---|
content_type | string |
filename | string |
id required | string |
size required | integer |
s3.BucketLinks
| Property | Type |
|---|
objects required | string |
self required | string |
s3.BucketView
| Property | Type |
|---|
bytes required | integer |
creation_time required | string (date-time) |
links required | s3.BucketLinks |
name required | string |
objects required | integer |
s3.Checksums
| Property | Type |
|---|
crc32 | string |
crc32c | string |
sha1 | string |
sha256 | string |
s3.CommonPrefixView
| Property | Type |
|---|
list required | string |
prefix required | string |
s3.ObjectLinks
| Property | Type |
|---|
content required | string |
list required | string |
self required | string |
s3.ObjectView
| Property | Type |
|---|
blob required | blob.Ref |
bucket required | string |
checksums required | s3.Checksums |
etag required | string |
headers required | s3.ContentHeaders |
key required | string |
last_modified required | string (date-time) |
links required | s3.ObjectLinks |
metadata | object of string |
size required | integer |
s3.ObjectsView
| Property | Type |
|---|
bucket required | s3.BucketView |
common_prefixes required | array of s3.CommonPrefixView |
continuation_token | string |
delimiter | string |
is_truncated required | boolean |
max_keys required | integer |
next | string |
next_continuation_token | string |
objects required | array of s3.ObjectView |
prefix | string |
self required | string |
start_after | string |
s3.Stats
| Property | Type |
|---|
active_uploads required | integer |
buckets required | integer |
bytes required | integer |
objects required | integer |
part_bytes required | integer |
parts required | integer |