tommy files API v1
Accepts the files your application uploads over FTP, SFTP or TFTP instead of shipping them anywhere, and keeps them in a virtual filesystem you can browse, download from and assert against. Every upload, mkdir, delete and rename is also recorded as an event, so the tree shows what is there now and the log shows how it got that way.
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/files — This tommy's files API.
Operations
GET
/content/{path}
A file's bytes, streamed from the blob store with range support.
Parameters
| Name | In | Type | Description |
|---|
path required |
path |
string |
Path inside the shared virtual filesystem. It may contain slashes: this is the whole remaining path, not one segment. |
Responses
| Status | Body | Description |
|---|
200 |
application/octet-stream
|
Success. |
404 |
application/json · api.Error
|
No such resource, or it belongs to another plugin. |
DELETE
/content/{path}
Delete one file, or a directory with ?recursive=1.
Parameters
| Name | In | Type | Description |
|---|
path required |
path |
string |
Path inside the shared virtual filesystem. It may contain slashes: this is the whole remaining path, not one segment. |
recursive |
query |
boolean |
Required to delete a directory, so a mistyped path cannot take a subtree with it. |
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
/stat/{path}
One entry's metadata: size, mode, times, and which provider wrote it.
Parameters
| Name | In | Type | Description |
|---|
path required |
path |
string |
Path inside the shared virtual filesystem. It may contain slashes: this is the whole remaining path, not one segment. |
Responses
| Status | Body | Description |
|---|
200 |
application/json · files.EntryView
|
Success. |
404 |
application/json · api.Error
|
No such resource, or it belongs to another plugin. |
GET
/tree
One directory of the shared virtual filesystem, or the whole subtree.
Parameters
| Name | In | Type | Description |
|---|
path |
query |
string |
The directory to list; the root when omitted. |
recursive |
query |
boolean |
List the whole subtree rather than one level. |
Responses
| Status | Body | Description |
|---|
200 |
application/json · files.TreeView
|
Success. |
400 |
application/json · api.Error
|
A query parameter could not be parsed - a malformed since, a negative limit. |
DELETE
/tree
Empty the virtual filesystem.
Responses
| Status | Body | Description |
|---|
204 |
no body |
Done. No body. |
Schemas
api.Error
| Property | Type |
|---|
error required | string |
blob.Ref
| Property | Type |
|---|
content_type | string |
filename | string |
id required | string |
size required | integer |
files.Crumb
| Property | Type |
|---|
name required | string |
path required | string |
url required | string |
files.EntryLinks
| Property | Type |
|---|
content | string |
self required | string |
tree | string |
files.EntryView
| Property | Type |
|---|
blob required | blob.Ref |
content_type | string |
dir required | boolean |
links required | files.EntryLinks |
mod_time required | string (date-time) |
name required | string |
path required | string |
provider | string |
size required | integer |
files.Stats
| Property | Type |
|---|
bytes required | integer |
dirs required | integer |
files required | integer |