9e8f0a412f
- Modified config.py to use environment variables for storage paths - Added better error handling for directory creation - Updated file_service.py to handle permission errors gracefully - Changed default storage path to './storage' instead of '/app/storage' - Added comprehensive documentation about storage configuration - Added logging for better debugging of file operations - Updated README with storage configuration guidelines
184 lines
4.7 KiB
Markdown
184 lines
4.7 KiB
Markdown
# File Upload/Download API
|
|
|
|
A FastAPI-based REST API for uploading, downloading, and managing files with SQLite database for metadata storage.
|
|
|
|
## Features
|
|
|
|
- Upload files with size validation
|
|
- Download files by ID
|
|
- List all uploaded files
|
|
- Get detailed file metadata
|
|
- Delete files
|
|
- Health check endpoint
|
|
- OpenAPI documentation
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.8+
|
|
- pip (Python package manager)
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd fileuploaddownloadapi
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. Run database migrations:
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Running the Server
|
|
|
|
Start the application with uvicorn:
|
|
|
|
```bash
|
|
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
|
|
```
|
|
|
|
The API will be available at `http://localhost:8000`.
|
|
|
|
### API Documentation
|
|
|
|
Interactive API documentation is available at:
|
|
- Swagger UI: `http://localhost:8000/docs`
|
|
- ReDoc: `http://localhost:8000/redoc`
|
|
|
|
### API Endpoints
|
|
|
|
#### File Operations
|
|
|
|
- **Upload a file**
|
|
- `POST /api/v1/files/`
|
|
- Request: Form data with a file
|
|
- Response: File metadata with download URL
|
|
|
|
- **List all files**
|
|
- `GET /api/v1/files/`
|
|
- Response: Array of file metadata objects
|
|
|
|
- **Get file metadata**
|
|
- `GET /api/v1/files/{file_id}`
|
|
- Response: File metadata object
|
|
|
|
- **Download a file**
|
|
- `GET /api/v1/files/{file_id}/download`
|
|
- Response: File content as a binary stream
|
|
|
|
- **Delete a file**
|
|
- `DELETE /api/v1/files/{file_id}`
|
|
- Response: No content (204)
|
|
|
|
#### Health Check
|
|
|
|
- **Health check endpoint**
|
|
- `GET /health`
|
|
- Response: `{"status": "healthy"}`
|
|
|
|
#### Root Endpoint
|
|
|
|
- **API Information**
|
|
- `GET /`
|
|
- Response: Basic API information and links
|
|
|
|
## Configuration
|
|
|
|
The API uses environment variables for configuration:
|
|
|
|
| Variable | Description | Default Value |
|
|
|----------------------|----------------------------------------------|------------------------|
|
|
| PROJECT_NAME | Name of the project | "File Upload Download API" |
|
|
| MAX_FILE_SIZE | Maximum allowed file size in bytes | 10485760 (10MB) |
|
|
| STORAGE_BASE_DIR | Base directory for all storage | "./storage" |
|
|
| FILE_STORAGE_DIR | Directory for storing uploaded files | "{STORAGE_BASE_DIR}/files" |
|
|
| DB_DIR | Directory for the SQLite database | "{STORAGE_BASE_DIR}/db" |
|
|
| SQLALCHEMY_DATABASE_URL | Full database connection URL | "sqlite:///{DB_DIR}/db.sqlite" |
|
|
|
|
## File Storage
|
|
|
|
By default, files are stored in the `./storage/files` directory. File metadata is stored in a SQLite database at `./storage/db/db.sqlite`.
|
|
|
|
### Storage in Containerized Environments
|
|
|
|
When running in a containerized environment like Docker, you should handle storage paths carefully:
|
|
|
|
1. **Using Volume Mounts**: Mount a persistent volume to the storage directory:
|
|
```bash
|
|
docker run -v /host/path/to/storage:/app/storage your-image-name
|
|
```
|
|
|
|
2. **Using Environment Variables**: Configure storage locations with environment variables:
|
|
```bash
|
|
docker run -e STORAGE_BASE_DIR=/data -v /host/path/to/data:/data your-image-name
|
|
```
|
|
|
|
3. **Pre-creating Directories**: Ensure directories exist with proper permissions:
|
|
```bash
|
|
mkdir -p ./storage/files ./storage/db
|
|
chmod 777 ./storage/files ./storage/db # For development only
|
|
```
|
|
|
|
> **Note**: The application will continue running even if it cannot create storage directories, but file operations will fail. This allows the application to start and serve documentation even if storage is not properly configured.
|
|
|
|
## Development
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
fileuploaddownloadapi/
|
|
├── app/
|
|
│ ├── api/
|
|
│ │ └── v1/
|
|
│ │ ├── api.py
|
|
│ │ └── endpoints/
|
|
│ │ └── files.py
|
|
│ ├── core/
|
|
│ │ └── config.py
|
|
│ ├── db/
|
|
│ │ ├── base.py
|
|
│ │ ├── session.py
|
|
│ │ └── migrations/
|
|
│ │ └── versions/
|
|
│ │ └── 001_create_files_table.py
|
|
│ ├── models/
|
|
│ │ └── file.py
|
|
│ ├── schemas/
|
|
│ │ └── file.py
|
|
│ └── services/
|
|
│ └── file_service.py
|
|
├── storage/
|
|
│ ├── db/
|
|
│ └── files/
|
|
├── alembic.ini
|
|
├── main.py
|
|
└── requirements.txt
|
|
```
|
|
|
|
### Running Migrations
|
|
|
|
```bash
|
|
# Create a new migration
|
|
alembic revision -m "description"
|
|
|
|
# Apply all migrations
|
|
alembic upgrade head
|
|
|
|
# Rollback a migration
|
|
alembic downgrade -1
|
|
|
|
# Check current migration version
|
|
alembic current
|
|
```
|
|
|
|
## License
|
|
|
|
[MIT License](LICENSE) |