Chapters: 
Camelot

README.md for TransferDepot repo

Overview

  • API routes with curl examples
  • Expected JSON responses (with your new group/files shape + relative URLs)
  • A quick note on deployment/testing

 

📦 TransferDepot — API Quick Reference

TransferDepot is a Flask-based file transfer service.
This document provides quick curl examples and expected JSON responses for testing the API.

All examples assume the service is running locally on port 8080.
When accessed through the sh1re gateway (reverse proxy), replace http://127.0.0.1:8080 with https://transferdepot.sh1re.net.

🔹 1. Health Check

Verify the service is alive. 

curl -i http://127.0.0.1:8080/api/v1/healthz

Response: 

{"status": "ok"}

🔹 2. List Files in a Group

Return a JSON object describing all files in the given group. 

curl -i http://127.0.0.1:8080/api/v1/files/FOO

Response: 

{
  "group": "FOO",
  "files": [
    {
      "name": "abcd.txt",
      "url": "/api/v1/files/FOO/abcd.txt",
      "modified": "2025-09-15 17:41:03"
    }
  ]
}

🔹 3. Upload a File

Upload example.txt into the FOO group. 

curl -i -X POST \
  -F "file=@example.txt" \
  http://127.0.0.1:8080/upload-basic/FOO

Response: 

HTTP/1.1 303 SEE OTHER
Location: /upload-basic/FOO

🔹 4. Download a File

Download a specific file from a group. 

curl -O http://127.0.0.1:8080/files/FOO/abcd.txt

🔹 5. Order Files by Date (Optional)

Return files in FOO ordered by upload time (newest first). 

curl -i http://127.0.0.1:8080/api/v1/files/FOO?order=desc

🔹 Example Route Implementation 

import os
import time
from flask import jsonify

def file_metadata(name, group):
    return {
        "name": name,
        "url": f"/api/v1/files/{group}/{name}",
        "modified": time.strftime(
            "%Y-%m-%d %H:%M:%S",
            time.localtime(os.path.getmtime(os.path.join("uploads", group, name)))
        )
    }

@app.route("/api/v1/files/<group>")
def list_files(group):
    directory = os.path.join("uploads", group)
    if not os.path.exists(directory):
        return jsonify({"group": group, "files": []})

    files = []
    for fname in os.listdir(directory):
        fpath = os.path.join(directory, fname)
        if os.path.isfile(fpath):
            files.append(file_metadata(fname, group))

    return jsonify({"group": group, "files": files})

🔹 Notes

  • All URLs are relative → this ensures smooth operation behind Nginx/sh1re.
  • Uploads persist in the uploads/<group> directories (mapped as volumes in Podman).
  • For container deployment, see the included Dockerfile, podman-compose.yml, and Makefile.

✅ That’s your one-page API doc — lightweight, testable, and easy to share.