fileuploaddownloadapi-chkcyo/README.md

# 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)