README.md

metadata

title: MinIO Storage API
emoji: 🗃️
colorFrom: blue
colorTo: green
sdk: docker
app_file: app.py
pinned: false
license: mit

MinIO File Storage Service

A complete file storage API with FastAPI backend, MinIO object storage, and PostgreSQL metadata management.

🚀 Features

• 🔐 Dual Authentication - JWT tokens and API keys
• 🎯 Granular Permissions - Fine-grained access control
• 🌐 Public File Sharing - Share files with public URLs
• 📁 Project-based Storage - Isolated storage per project
• 🔑 API Key Management - Generate keys with specific permissions
• 📤 Direct Upload API - Upload files with API keys
• 🖼️ Inline File Viewing - View images, PDFs in browser
• ⬇️ Public Downloads - Download files without authentication

🔒 API Key Permissions

Permission	Description
read	View file metadata
write	Upload new files
delete	Delete files
list	List all files
public	Generate public URLs
download	Download files

Permission Presets

• Read-only: read,list,download
• Upload only: write
• Full access: read,write,delete,list,public,download

📖 Quick Start

1. Initialize Admin

POST /init-admin

2. Login

POST /auth/login
{
  "username": "admin",
  "password": "your_admin_password"
}

3. Create Project

POST /projects
Authorization: Bearer <your_jwt_token>
{
  "name": "My Project",
  "description": "Project description"
}

4. Generate API Key

POST /projects/{project_id}/api-keys
Authorization: Bearer <your_jwt_token>
{
  "name": "Upload Key",
  "permissions": "write,public",
  "description": "Key for uploading files"
}

5. Upload Files

curl -X POST "https://godfreyowino-minio-storage-api.hf.space/api/upload" \
  -H "X-API-Key: sk_your_api_key" \
  -F "file=@image.jpg"

📚 API Endpoints

Authentication

• POST /auth/register - Register user
• POST /auth/login - Login user
• GET /users/me - Get user info
• POST /init-admin - Initialize admin

Projects (JWT Required)

• POST /projects - Create project
• GET /projects - List projects
• GET /projects/{id} - Get project

API Keys (JWT Required)

• POST /projects/{id}/api-keys - Create API key
• GET /projects/{id}/api-keys - List API keys
• DELETE /projects/{id}/api-keys/{key_id} - Revoke key

Files (JWT Auth)

• POST /projects/{id}/upload - Upload file
• GET /projects/{id}/files - List files
• GET /projects/{id}/files/{file_id}/download - Download
• DELETE /projects/{id}/files/{file_id} - Delete

Files (API Key Auth)

• POST /api/upload - Upload file
• GET /api/files - List files
• GET /api/files/{file_id} - Get file metadata
• GET /api/files/{file_id}/download - Download
• GET /api/files/{file_id}/public-url - Get public URL
• DELETE /api/files/{file_id} - Delete

Public Access (No Auth)

• GET /public/files/{file_id} - View file inline
• GET /public/download/{file_id} - Download file

💻 Usage Examples

Python

import requests

API_KEY = "sk_your_api_key"
BASE_URL = "https://godfreyowino-minio-storage-api.hf.space"

# Upload file
with open("image.jpg", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/api/upload",
        headers={"X-API-Key": API_KEY},
        files={"file": f}
    )
    result = response.json()
    print(f"Public URL: {result['public_url']}")

# List files
response = requests.get(
    f"{BASE_URL}/api/files",
    headers={"X-API-Key": API_KEY}
)
files = response.json()

JavaScript

const API_KEY = "sk_your_api_key";
const BASE_URL = "https://godfreyowino-minio-storage-api.hf.space";

// Upload file
const uploadFile = async (file) => {
  const formData = new FormData();
  formData.append('file', file);

  const response = await fetch(`${BASE_URL}/api/upload`, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY },
    body: formData
  });

  const data = await response.json();
  return data.public_url;
};

HTML

<!-- Display image -->
<img src="https://godfreyowino-minio-storage-api.hf.space/public/files/{file-id}" 
     alt="Uploaded image">

<!-- Download link -->
<a href="https://godfreyowino-minio-storage-api.hf.space/public/download/{file-id}">
  Download File
</a>

🔧 Environment Variables

Required variables for HuggingFace Spaces:

DATABASE_URL=your_postgresql_url
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_SECURE=false
SECRET_KEY=your_secret_key
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your_admin_password
PUBLIC_URL=https://godfreyowino-minio-storage-api.hf.space

📖 Documentation

Interactive API docs: /docs

License

MIT License