📷 Images API (NestJS)

Simple REST API for uploading, resizing, and serving images. The service stores metadata in PostgreSQL (or SQLite for tests) and stores files on the filesystem.

✨ Features

• POST /images for image upload with title, width, and height
• GET /images with pagination and title filtering
• GET /images/:id for single image
• Files served from /uploads/*
• Swagger OpenAPI v3 docs at http://localhost:3000/docs

🧰 Requirements

• Node.js LTS
• Docker + docker-compose (recommended)

🐳 Quick Start (Docker)

1. Build and run:

docker-compose up --build

2. Open Swagger UI:

http://localhost:3000/docs

🧪 Local Development

1. Install deps:

npm install

2. Create env file:

copy .env.example .env

3. Start the API:

npm run start:dev

⚙️ Environment Variables

See .env.example for defaults. The most important:

• PORT (default 3000)
• UPLOAD_DIR (default uploads)
• UPLOAD_MAX_FILE_SIZE (bytes, default 10485760)
• DB_TYPE (postgres or sqlite)
• DB_* settings for Postgres
• DB_SYNC (default false, use migrations)
• DB_MIGRATIONS_RUN (default true, auto-runs migrations on startup)
• IMAGES_OUTPUT_FORMAT (source or jpeg)
• IMAGES_JPEG_QUALITY / IMAGES_WEBP_QUALITY / IMAGES_AVIF_QUALITY (1-100)
• IMAGES_PNG_COMPRESSION_LEVEL (0-9)

🧱 Architecture

The project follows a simplified Clean Architecture layout:

• src/presentation — controllers, HTTP DTOs, upload config
• src/application — use-cases (ImagesService), application DTOs, ports
• src/domain — domain types
• src/infrastructure — persistence, storage, config, migrations

🗃️ Migrations

Migrations are enabled by default (DB_MIGRATIONS_RUN=true) and DB_SYNC is disabled to avoid schema sync warnings. You can toggle them via env if needed.

🧭 API Details

POST /images

• Content-Type: multipart/form-data
• Fields:
  • file (image file)
  • title (string)
  • width (int)
  • height (int)

Response:

{
  "id": "uuid",
  "url": "/uploads/<filename>",
  "title": "My image",
  "width": 800,
  "height": 600
}

GET /images

Query params:

• title (optional, substring match)
• page (optional, default 1)
• limit (optional, default 20, max 100)

Response:

{
  "data": [
    {
      "id": "uuid",
      "url": "/uploads/<filename>",
      "title": "My image",
      "width": 800,
      "height": 600
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

GET /images/:id

Returns a single image object.

✅ Tests

Run e2e tests (SQLite in-memory):

npm test

📝 Notes

• Images are resized using sharp with fit=cover (crop + scale). Output format and compression are configurable via env.
• Files are stored on disk in UPLOAD_DIR and served via /uploads.