Skip to main content

uploads-api

Uploads API

  • Base Paths:
    • User: /api/v1/uploads
    • Admin: /api/admin/uploads
  • Auth: Bearer token required for user; admin area per admin auth

Overview

  • Supports uploading images to S3 via multipart/form-data.
  • Returns a public url you can store and use (e.g., as a user avatar or product image).
  • Files are uploaded to uploads/YYYY-MM-DD/<timestamp>_<originalname>.

Environment

  • AWS_REGION (or AWS_DEFAULT_REGION): AWS region.
  • AWS_ACCESS_KEY_ID: AWS access key.
  • AWS_SECRET_ACCESS_KEY: AWS secret key.
  • AWS_S3_BUCKET: Target S3 bucket name.
  • S3_PUBLIC_BASE_URL (optional): CDN base (e.g., CloudFront). If provided, returned url uses this base.
  • S3_USE_ACL (optional): Set to true only if your bucket requires ACL (most modern buckets use Bucket Owner Enforced and reject ACLs).

If any required variables are missing, the server responds with 500 and S3 is not configured....

Endpoints

  • Upload Image (User)

    • Method: POST
    • Path: /api/v1/uploads/image
    • Auth: Bearer required
    • Body: multipart/form-data with field file
    • Response 201:
      • url: string — public URL to the uploaded file
      • key: string — S3 object key
      • contentType: string — detected or provided content type
      • size: number — size in bytes
      • name: string — original filename
    • Errors:
      • 400: \{ "error": "file is required (multipart field name: file)" \}
      • 500: \{ "error": "Failed to upload image" \}

  • Upload Image (Admin)

    • Method: POST
    • Path: /api/admin/uploads/image
    • Auth: Admin
    • Body and response: same as the user endpoint.

Usage: Set User Avatar

  1. Upload image to get a URL:

curl -X POST
-H "Authorization: Bearer <token>"
-F "file=@/path/to/avatar.png"
https://<host>/api/v1/uploads/image

Response:

{
  "url": "https://cdn.example.com/uploads/2025-09-01/1693552800000_avatar.png",
  "key": "uploads/2025-09-01/1693552800000_avatar.png",
  "contentType": "image/png",
  "size": 12345,
  "name": "avatar.png"
}
  1. Save the URL as your avatar:

curl -X PATCH
-H "Authorization: Bearer <token>"
-H "Content-Type: application/json"
-d '{ "avatar": "https://cdn.example.com/uploads/2025-09-01/1693552800000_avatar.png" }'
https://<host>/api/v1/users/me

Response: updated user document including avatar.

Notes

  • Current implementation uses in-memory buffering (multer.memoryStorage()), which is fine for modest file sizes. For large files, consider size limits and type validation.
  • Allowed file types are inferred from the uploaded filename and mimetype; adjust server-side validation as needed.