File Storage API

A robust file storage and sharing API built with Go and Gin web framework, designed for easy file management with PostgreSQL database integration.

🚀 Features

• File Upload: Upload files with automatic unique ID generation
• File Download: Download files by their unique ID
• File Listing: Retrieve all stored files metadata
• File Deletion: Delete files by ID (removes both file and database record)
• Health Check: API health monitoring endpoint
• Secure Storage: Files stored with UUID-based naming to prevent conflicts
• PostgreSQL Integration: Robust database support for file metadata
• Environment Configuration: Secure configuration via environment variables

🛠 Tech Stack

• Language: Go 1.23.0
• Web Framework: Gin Web Framework
• Database: PostgreSQL
• File Handling: Multipart form data
• UUID Generation: Google UUID library
• Environment Management: godotenv

📋 Prerequisites

Before running this application, make sure you have the following installed:

• Go 1.23.0 or higher
• PostgreSQL database
• Git (for cloning the repository)

⚙️ Installation & Setup

1. Clone the repository

   git clone https://github.com/Fonate-Michael/File-Storage-API.git
   cd file-storage-api

2. Install dependencies

   go mod download

3. Set up environment variables

   Create a .env file in the root directory with the following variables:

   DB_USER=your_db_username
   DB_PASS=your_db_password
   DB_NAME=your_database_name
   DB_SSL=disable
   UPLOADS_DIR=./uploads/

4. Set up PostgreSQL database

   Create a PostgreSQL database and run the following SQL to create the required table:

   CREATE TABLE file_meta_data (
       id VARCHAR(255) PRIMARY KEY,
       file_name VARCHAR(255) NOT NULL,
       storage_path TEXT NOT NULL
   );

5. Build and run the application

   go build -o file-storage-api
   ./file-storage-api

The API will start running on http://localhost:8000

📁 Project Structure

file-storage-api/
│
├── main.go                 # Application entry point
├── go.mod                  # Go module definition
├── go.sum                  # Go dependencies checksum
├── .env                     # Environment variables (gitignored)
├── .gitignore              # Git ignore rules
│
├── db/
│   └── db.go              # Database connection and setup
│
├── models/
│   └── file.go            # File data model
│
├── handlers/
│   └── file_handler.go    # HTTP request handlers
│
├── routes/
│   └── routes.go          # Route definitions
│
└── uploads/               # File storage directory
    └── ...                # Uploaded files with UUID suffixes

🔌 API Endpoints

Health Check

• GET /health
• Description: Check API health status
• Response:

  {
    "health": "API is running with success you can try endpoints like /upload /files /files/:id"
  }

Upload File

• POST /upload
• Description: Upload a file to the server
• Content-Type: multipart/form-data
• Body: Form data with file field containing the file
• Response (Success 200):

  {
    "file_meta_data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "file_name": "example.txt",
      "storage_path": "./uploads/example.txt_550e8400-e29b-41d4-a716-446655440000.txt"
    }
  }

• Response (Error 502):

  {
    "message": "Please upload a file ma boi"
  }

Get All Files

• GET /files
• Description: Retrieve metadata of all stored files
• Response (Success 200):

  {
    "files": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "file_name": "example.txt",
        "storage_path": "./uploads/example.txt_550e8400-e29b-41d4-a716-446655440000.txt"
      }
    ]
  }

• Response (Error 500):

  {
    "error": "Failed to fetch files"
  }

Download File

• GET /files/:id
• Description: Download a file by its ID
• URL Parameters:
  • id (string): Unique file identifier
• Response: File download with appropriate headers
• Response (Error 500):

  {
    "error": "Failed to fetch file meta data"
  }

Delete File

• DELETE /files/:id
• Description: Delete a file by its ID (removes both file and database record)
• URL Parameters:
  • id (string): Unique file identifier
• Response (Success 200):

  {
    "message": "File deleted successfully"
  }

• Response (Error 500):

  {
    "error": "Failed to fetch file meta data"
  }

🧪 Usage Examples

Upload a file using curl

curl -X POST -F "file=@/path/to/your/file.txt" http://localhost:8000/upload

Get all files

curl http://localhost:8000/files

Download a file

curl -O -J http://localhost:8000/files/550e8400-e29b-41d4-a716-446655440000

Delete a file

curl -X DELETE http://localhost:8000/files/550e8400-e29b-41d4-a716-446655440000

Check API health

curl http://localhost:8000/health

🔒 Security Features

• Unique File IDs: Each uploaded file gets a unique UUID to prevent naming conflicts
• Path Sanitization: File paths are properly sanitized using filepath.Base()
• Environment Variables: Sensitive configuration stored in environment variables
• Error Handling: Comprehensive error handling for file operations

🚨 Error Handling

The API includes comprehensive error handling for:

• Missing files in upload requests
• Database connection failures
• File system errors
• Invalid file IDs
• Missing environment variables

📝 Environment Variables

Variable	Description	Required	Default
DB_USER	PostgreSQL database username	Yes	-
DB_PASS	PostgreSQL database password	Yes	-
DB_NAME	PostgreSQL database name	Yes	-
DB_SSL	SSL mode for database connection	Yes	disable
UPLOADS_DIR	Directory for file storage	Yes	./uploads/

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Fonate Michael

---

Built with ❤️ using Go and Gin Web Framework