File Management Service

The File Management Service provides endpoints for uploading, retrieving, and managing files within the NextGate platform. All files are organized by directories and associated with user accounts.

Important Notes

⚠️ All endpoints are protected and require authentication

💡 Recommended: Use the multiple file upload endpoint (/upload) even for single files as it provides better error handling and batch processing capabilities.

Base URL

/api/v1/files

Authentication

All endpoints require JWT authentication. Include the Bearer token in the Authorization header.

---

File Directories

Files are organized into predefined directories:

Directory	Description
PROFILE	User profile images and documents
CATEGORIES	Category-related images and media
SHOPS	Shop images, logos, and media

---

Upload Multiple Files

Upload multiple files to a specified directory.

POST /upload

Request Parameters

Parameter	Type	Required	Description
files	File[]	Yes	Array of files to upload (multipart/form-data)
directory	String	Yes	Target directory (PROFILE, CATEGORIES, SHOPS)

Success Response

Code: 200 OK

{
  "success": true,
  "message": "Files uploaded successfully",
  "data": {
    "uploadedFiles": [
      {
        "fileName": "550e8400-e29b-41d4-a716-446655440000.jpg",
        "originalFileName": "image1.jpg",
        "objectKey": "profile/550e8400-e29b-41d4-a716-446655440000.jpg",
        "directory": "PROFILE",
        "contentType": "image/jpeg",
        "fileSize": 2048576,
        "fileSizeFormatted": "2.0 MB",
        "permanentUrl": "http://localhost:9005/bucket-name/profile/550e8400-e29b-41d4-a716-446655440000.jpg",
        "thumbnailUrl": "http://localhost:9005/bucket-name/profile/550e8400-e29b-41d4-a716-446655440000.jpg",
        "fileExtension": ".jpg",
        "fileType": "IMAGE",
        "isImage": true,
        "isVideo": false,
        "isDocument": false,
        "isAudio": false,
        "width": 1920,
        "height": 1080,
        "dimensions": "1920x1080",
        "checksum": "d41d8cd98f00b204e9800998ecf8427e",
        "uploadedAt": "2024-01-20T10:30:00",
        "uploadedBy": "123e4567-e89b-12d3-a456-426614174000",
        "isPublic": true
      }
    ],
    "totalFiles": 2,
    "successfulUploads": 1,
    "failedUploads": 1,
    "totalSize": 2048576,
    "totalSizeFormatted": "2.0 MB",
    "uploadedAt": "2024-01-20T10:30:00",
    "message": "1 files uploaded successfully, 1 failed",
    "errors": [
      "Failed to upload document.pdf: File size exceeds maximum limit of 25MB"
    ]
  }
}

---

Upload Single File

Upload a single file to a specified directory.

POST /upload-single

Request Parameters

Parameter	Type	Required	Description
file	File	Yes	File to upload (multipart/form-data)
directory	String	Yes	Target directory (PROFILE, CATEGORIES, SHOPS)

Success Response

Code: 200 OK

{
  "success": true,
  "message": "File uploaded successfully",
  "data": {
    "fileName": "550e8400-e29b-41d4-a716-446655440000.jpg",
    "originalFileName": "profile-image.jpg",
    "objectKey": "profile/550e8400-e29b-41d4-a716-446655440000.jpg",
    "directory": "PROFILE",
    "contentType": "image/jpeg",
    "fileSize": 1024000,
    "fileSizeFormatted": "1.0 MB",
    "permanentUrl": "http://localhost:9005/bucket-name/profile/550e8400-e29b-41d4-a716-446655440000.jpg",
    "thumbnailUrl": "http://localhost:9005/bucket-name/profile/550e8400-e29b-41d4-a716-446655440000.jpg",
    "fileExtension": ".jpg",
    "fileType": "IMAGE",
    "isImage": true,
    "isVideo": false,
    "isDocument": false,
    "isAudio": false,
    "width": 800,
    "height": 600,
    "dimensions": "800x600",
    "checksum": "5d41402abc4b2a76b9719d911017c592",
    "uploadedAt": "2024-01-20T10:30:00",
    "uploadedBy": "123e4567-e89b-12d3-a456-426614174000",
    "isPublic": true
  }
}

---

Get User Files by Directory

Retrieve all files for the authenticated user in a specific directory.

GET /directory/{directory}

Path Parameters

Parameter	Type	Required	Description
directory	String	Yes	Directory to list files from (PROFILE, CATEGORIES, SHOPS)

Success Response

Code: 200 OK

{
  "success": true,
  "message": "Files retrieved successfully",
  "data": [
    {
      "fileName": "550e8400-e29b-41d4-a716-446655440000.jpg",
      "originalFileName": "profile-image.jpg",
      "objectKey": "profile/550e8400-e29b-41d4-a716-446655440000.jpg",
      "directory": "PROFILE",
      "contentType": "image/jpeg",
      "fileSize": 1024000,
      "fileSizeFormatted": "1.0 MB",
      "permanentUrl": "http://localhost:9005/bucket-name/profile/550e8400-e29b-41d4-a716-446655440000.jpg",
      "thumbnailUrl": "http://localhost:9005/bucket-name/profile/550e8400-e29b-41d4-a716-446655440000.jpg",
      "fileExtension": ".jpg",
      "fileType": "IMAGE",
      "isImage": true,
      "isVideo": false,
      "isDocument": false,
      "isAudio": false,
      "width": 800,
      "height": 600,
      "dimensions": "800x600",
      "uploadedAt": "2024-01-20T10:30:00",
      "uploadedBy": "123e4567-e89b-12d3-a456-426614174000",
      "isPublic": true
    }
  ]
}

---

Delete File

Delete a specific file using its object key.

DELETE /{objectKey}

Path Parameters

Parameter	Type	Required	Description
objectKey	String	Yes	The unique object key of the file to delete

Success Response

Code: 200 OK

{
  "success": true,
  "message": "File deleted successfully"
}

---

Data Models

FileResponse

Field	Type	Description
fileName	String	Generated unique filename
originalFileName	String	Original filename from upload
objectKey	String	MinIO object key for the file
directory	String	Directory where file is stored
contentType	String	MIME type of the file
fileSize	Long	File size in bytes
fileSizeFormatted	String	Human-readable file size
permanentUrl	String	Direct URL to access the file
thumbnailUrl	String	Thumbnail URL (for images/videos)
fileExtension	String	File extension with dot
fileType	String	Category: IMAGE, VIDEO, DOCUMENT, AUDIO, OTHER
isImage	Boolean	Whether file is an image
isVideo	Boolean	Whether file is a video
isDocument	Boolean	Whether file is a document
isAudio	Boolean	Whether file is an audio file
width	Integer	Image/video width in pixels
height	Integer	Image/video height in pixels
dimensions	String	Formatted dimensions
duration	Long	Video duration in seconds
durationFormatted	String	Formatted duration
checksum	String	MD5 hash of the file
uploadedAt	DateTime	Upload timestamp
uploadedBy	String	Account ID of uploader
isPublic	Boolean	Whether file is publicly accessible
description	String	Optional file description
tags	String[]	Optional file tags

FileUploadResponse

Field	Type	Description
uploadedFiles	FileResponse[]	Array of successfully uploaded files
totalFiles	Integer	Total number of files attempted
successfulUploads	Integer	Number of successful uploads
failedUploads	Integer	Number of failed uploads
totalSize	Long	Total size of all uploaded files in bytes
totalSizeFormatted	String	Human-readable total size
uploadedAt	DateTime	Upload timestamp
message	String	Summary message
errors	String[]	Array of error messages (if any)

---

Supported File Types

Images

• JPEG/JPG, PNG, GIF, WebP, BMP, SVG

Videos

• MP4, AVI, MOV, WMV, FLV, WebM, MKV

Documents

• PDF, Word, Text, Excel

Audio

• MP3, WAV, OGG, AAC

---

File Constraints

• Maximum file size: 25 MB per file

• All uploaded files are publicly accessible

• Files are isolated by user account and directory

• System automatically generates unique filenames

• Metadata is automatically extracted for images

---

Error Responses

400 Bad Request

{
  "success": false,
  "message": "File size exceeds maximum limit of 25MB"
}

401 Unauthorized

{
  "success": false,
  "message": "User not authenticated"
}

404 Not Found

{
  "success": false,
  "message": "User not found"
}

500 Internal Server Error

{
  "success": false,
  "message": "Failed to upload file: Connection timeout"
}