forgejo_admin/minio-api
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

Build FastAPI service wrapping minio-sdk operations #1

New issue
Closed
opened 2026-03-22 06:49:20 +00:00 by forgejo_admin · 0 comments
forgejo_admin commented 2026-03-22 06:49:20 +00:00
Owner
Copy link

Type

Feature

Repo

forgejo_admin/minio-api

Lineage

plan-minio-mobile → Phase 2 → Phase 2a (FastAPI Routes)

User Story

As a frontend developer
I want a JSON REST API that wraps all MinIO S3 operations
So that I can build a mobile UI without dealing with S3 XML, Signature V4, or MinIO credentials in the browser

Context

The minio-sdk (v0.1.0, forgejo_admin/minio-sdk) provides a Python client for MinIO's S3 API with custom Signature V4 signing. This service wraps it as a FastAPI REST API with JSON request/response. No auth in this phase — that's Phase 2b. This ships as a tailnet-only service first.

The SDK is published to Forgejo PyPI. Install it as a dependency: pip install minio-sdk --index-url https://forgejo.tail5b443a.ts.net/api/packages/forgejo_admin/pypi/simple/

Key decisions:

  • minio-sdk as pip dependency — import MinioClient from the published package, don't copy code
  • JSON in, JSON out — SDK handles S3 XML internally, API consumers see only JSON
  • Pydantic models for request/response validation
  • No auth in this phase — Phase 2b adds Keycloak middleware
  • Presigned URLs — dedicated endpoints for generating download/upload URLs
  • OpenAPI auto-generated — FastAPI gives us /docs (Swagger UI) and /openapi.json for free

File Targets

Files to create:

  • src/minio_api/__init__.py — package init
  • src/minio_api/main.py — FastAPI app, lifespan, MinioClient initialization
  • src/minio_api/routes/buckets.py — bucket CRUD routes
  • src/minio_api/routes/objects.py — object CRUD + list routes
  • src/minio_api/routes/presign.py — presigned URL generation routes
  • src/minio_api/routes/multipart.py — multipart upload routes
  • src/minio_api/schemas.py — Pydantic models for request/response
  • src/minio_api/dependencies.py — shared dependencies (MinioClient instance)
  • tests/test_buckets.py — bucket route integration tests
  • tests/test_objects.py — object route integration tests
  • tests/test_presign.py — presigned URL tests
  • pyproject.toml — project config, minio-sdk dependency from Forgejo PyPI
  • CLAUDE.md — agent conventions

Acceptance Criteria

  • 15 REST endpoints covering all SDK operations (see route table below)
  • All endpoints return JSON (no XML exposed to consumers)
  • Pydantic models validate request/response schemas
  • /docs serves Swagger UI with interactive try-it-out
  • /openapi.json serves the OpenAPI spec
  • MinIO credentials from env vars (MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_ENDPOINT)
  • Presigned URL endpoints generate valid download/upload URLs
  • Integration tests pass against live MinIO
  • minio-sdk installed from Forgejo PyPI, not vendored

API Routes

# Bucket operations
GET    /api/buckets                              → list buckets
POST   /api/buckets                              → create bucket
DELETE /api/buckets/{name}                        → delete bucket
HEAD   /api/buckets/{name}                        → check exists

# Object operations
GET    /api/buckets/{bucket}/objects              → list objects (query: prefix, delimiter, max_keys)
GET    /api/buckets/{bucket}/objects/{key:path}   → download / get metadata
PUT    /api/buckets/{bucket}/objects/{key:path}   → upload
DELETE /api/buckets/{bucket}/objects/{key:path}   → delete
POST   /api/buckets/{bucket}/objects/delete        → batch delete

# Presigned URLs
POST   /api/presign/get                           → generate presigned download URL
POST   /api/presign/put                           → generate presigned upload URL

# Multipart
POST   /api/buckets/{bucket}/objects/{key:path}/multipart          → initiate
POST   /api/buckets/{bucket}/objects/{key:path}/multipart/complete → complete
DELETE /api/buckets/{bucket}/objects/{key:path}/multipart          → abort

Test Expectations

  • Integration tests using httpx AsyncClient + FastAPI TestClient
  • Tests hit real MinIO via the SDK (same pattern as minio-sdk tests)
  • Test cleanup: create/delete test buckets and objects
  • Run command: pytest tests/ -v

Constraints

  • Only dependency on minio-sdk from Forgejo PyPI — do not vendor or copy SDK code
  • FastAPI + uvicorn for the server
  • Pydantic v2 for schemas
  • No auth middleware in this phase (Phase 2b)
  • Object keys can contain / — use {key:path} in FastAPI route params

Checklist

  • PR opened
  • Tests pass
  • No unrelated changes

Related

  • phase-minio-mobile-2a-fastapi-routes — phase note
  • project-minio-mobile — project this advances
### Type Feature ### Repo `forgejo_admin/minio-api` ### Lineage `plan-minio-mobile` → Phase 2 → Phase 2a (FastAPI Routes) ### User Story As a frontend developer I want a JSON REST API that wraps all MinIO S3 operations So that I can build a mobile UI without dealing with S3 XML, Signature V4, or MinIO credentials in the browser ### Context The minio-sdk (v0.1.0, `forgejo_admin/minio-sdk`) provides a Python client for MinIO's S3 API with custom Signature V4 signing. This service wraps it as a FastAPI REST API with JSON request/response. No auth in this phase — that's Phase 2b. This ships as a tailnet-only service first. The SDK is published to Forgejo PyPI. Install it as a dependency: `pip install minio-sdk --index-url https://forgejo.tail5b443a.ts.net/api/packages/forgejo_admin/pypi/simple/` Key decisions: - **minio-sdk as pip dependency** — import `MinioClient` from the published package, don't copy code - **JSON in, JSON out** — SDK handles S3 XML internally, API consumers see only JSON - **Pydantic models** for request/response validation - **No auth in this phase** — Phase 2b adds Keycloak middleware - **Presigned URLs** — dedicated endpoints for generating download/upload URLs - **OpenAPI auto-generated** — FastAPI gives us `/docs` (Swagger UI) and `/openapi.json` for free ### File Targets Files to create: - `src/minio_api/__init__.py` — package init - `src/minio_api/main.py` — FastAPI app, lifespan, MinioClient initialization - `src/minio_api/routes/buckets.py` — bucket CRUD routes - `src/minio_api/routes/objects.py` — object CRUD + list routes - `src/minio_api/routes/presign.py` — presigned URL generation routes - `src/minio_api/routes/multipart.py` — multipart upload routes - `src/minio_api/schemas.py` — Pydantic models for request/response - `src/minio_api/dependencies.py` — shared dependencies (MinioClient instance) - `tests/test_buckets.py` — bucket route integration tests - `tests/test_objects.py` — object route integration tests - `tests/test_presign.py` — presigned URL tests - `pyproject.toml` — project config, minio-sdk dependency from Forgejo PyPI - `CLAUDE.md` — agent conventions ### Acceptance Criteria - [ ] 15 REST endpoints covering all SDK operations (see route table below) - [ ] All endpoints return JSON (no XML exposed to consumers) - [ ] Pydantic models validate request/response schemas - [ ] `/docs` serves Swagger UI with interactive try-it-out - [ ] `/openapi.json` serves the OpenAPI spec - [ ] MinIO credentials from env vars (`MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, `MINIO_ENDPOINT`) - [ ] Presigned URL endpoints generate valid download/upload URLs - [ ] Integration tests pass against live MinIO - [ ] minio-sdk installed from Forgejo PyPI, not vendored ### API Routes ``` # Bucket operations GET /api/buckets → list buckets POST /api/buckets → create bucket DELETE /api/buckets/{name} → delete bucket HEAD /api/buckets/{name} → check exists # Object operations GET /api/buckets/{bucket}/objects → list objects (query: prefix, delimiter, max_keys) GET /api/buckets/{bucket}/objects/{key:path} → download / get metadata PUT /api/buckets/{bucket}/objects/{key:path} → upload DELETE /api/buckets/{bucket}/objects/{key:path} → delete POST /api/buckets/{bucket}/objects/delete → batch delete # Presigned URLs POST /api/presign/get → generate presigned download URL POST /api/presign/put → generate presigned upload URL # Multipart POST /api/buckets/{bucket}/objects/{key:path}/multipart → initiate POST /api/buckets/{bucket}/objects/{key:path}/multipart/complete → complete DELETE /api/buckets/{bucket}/objects/{key:path}/multipart → abort ``` ### Test Expectations - [ ] Integration tests using httpx AsyncClient + FastAPI TestClient - [ ] Tests hit real MinIO via the SDK (same pattern as minio-sdk tests) - [ ] Test cleanup: create/delete test buckets and objects - Run command: `pytest tests/ -v` ### Constraints - Only dependency on minio-sdk from Forgejo PyPI — do not vendor or copy SDK code - FastAPI + uvicorn for the server - Pydantic v2 for schemas - No auth middleware in this phase (Phase 2b) - Object keys can contain `/` — use `{key:path}` in FastAPI route params ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `phase-minio-mobile-2a-fastapi-routes` — phase note - `project-minio-mobile` — project this advances
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
forgejo_admin/minio-api#1
No description provided.