Skip to content

LotuxPunk/Hestia

Repository files navigation

Hestia

Hestia is a simple file manipulation service, it allows you to upload, download, delete and list files via a REST API.

This project intends to be a reliable and simple solution for small scale file manipulation and avoid the need to setup a full fledged cloud storage service.

Notice

  • Inter-server communication, since it's an api key based authentication, the key should be kept secret and not exposed to the client side.
  • It is intended to be used with small/constrained file sizes, the file you'll try to manipulate will be loaded into memory and then sent to the server. For large files, it's recommended to use a more robust solution like AWS S3, Google Cloud Storage or Azure Blob Storage.

1. Environment Variables

To run this project, you will need to add the following environment variables:

  • API_KEY, a random secret key that will be used to authenticate the requests.
  • BASE_DIRECTORY, the base directory where the files will be stored.

2. Documentation

2.1. Endpoints

2.1.1. Authorization

All requests must have the Authorization header with the value of a one-time-token generated by the server.

Since the API key is a secret, it should not be exposed to the client side, so the server will generate a one-time-token that will be used to authenticate the requests.

GET /v1/auth/token

Generates a one-time-token that will be used to authenticate the requests.

Query Parameters
Name Type Description
fileName string The name of the file that will be manipulated.
path string The path of the file that will be manipulated.
Headers
Name Type Description
Authorization string The API key.
Content-Type string application/json.
Accept string application/json.
Response
```json
{
    "token": "...",
}
```

⚠️ Token expiration time: 5 minutes.

2.1.2. File Manipulation

POST /v1/file

Uploads a file to the server.

Headers
Name Type Description
Authorization string The one-time-token.
Content-Type string application/json.
Accept string application/json.
Request Body
```json
{
    "fileName": "example.txt",
    "path": "/",
    "file": "base64-encoded-file"
}
```
GET /v1/file

Downloads a file from the server.

Query Parameters
Name Type Description
fileName string The name of the file that will be downloaded.
path string The path of the file that will be downloaded.
Headers
Name Type Description
Authorization string The one-time-token.
Content-Type string application/json.
Accept string application/json or application/octet-stream
Response

If the Accept header is application/json:

```json
{
    "fileName": "example.txt",
    "path": "/",
    "file": "base64-encoded-file"
}
```

If the Accept header is application/octet-stream: stream the file.

GET /v1/file/embed

Downloads a file from the server, usually used to embed the file in an <img>, <audio>, <video> or <iframe> tag.

Query Parameters
Name Type Description
fileName string The name of the file that will be downloaded.
path string The path of the file that will be downloaded.
token string The one-time-token.
download string Download filename (via Content-Disposition )
DELETE /v1/file

Deletes a file from the server.

Query Parameters
Name Type Description
fileName string The name of the file that will be deleted.
path string The path of the file that will be deleted.
recursive boolean If true, deletes all files in the path.

path is required, but fileName is optional. If fileName is not provided, it'll try to delete the whole path specified in path

recursive is optional, if true, it'll delete recursively all files in the path. (even nested directories)

Headers
Name Type Description
Authorization string The one-time-token.
Content-Type string application/json.
Accept string application/json.