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"
}
PreviousNexGate Authentication APINextProfile Management Service

Last updated