File Management Service

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-09-23
Version: v1.0

Short Description: The File Management Service handles file uploads, downloads, and management for the NextGate social commerce platform. This service provides secure file storage with support for multiple file types, automatic metadata extraction, and organized directory structures for profiles, categories, and shops.

Hints:

Maximum file size: 25MB per file
Supported file types: Images (JPEG, PNG, GIF, WebP, BMP, SVG), Videos (MP4, AVI, MOV, WebM, MKV), Documents (PDF, DOC, DOCX, TXT, XLS), Audio (MP3, WAV, OGG, AAC)
All uploaded files are publicly accessible via direct URLs
Files are automatically organized by directory type (profile, categories, shops)
Image dimensions and metadata are automatically extracted
Unique filenames are generated to prevent conflicts
MD5 checksums are calculated for file integrity verification

Endpoints

1. Upload Multiple Files

Purpose: Upload multiple files to a specified directory with comprehensive metadata extraction

Endpoint: POST https://apinexgate.glueauth.com/api/v1/files/upload

Access Level: 🔒 Protected (Requires JWT Bearer token)

Authentication: Bearer Token (JWT access token required)

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer {access_token}
Content-Type	string	Yes	Must be "multipart/form-data"

Request Form Data Parameters:

Parameter	Type	Required	Description	Validation
files	file[]	Yes	Array of files to upload	Max 25MB per file, supported file types only
directory	string	Yes	Target directory for files	enum: PROFILE, CATEGORIES, SHOPS

Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Files uploaded successfully",
  "action_time": "2025-09-23T10:30:00",
  "data": {
    "uploadedFiles": [
      {
        "fileName": "123e4567-e89b-12d3-a456-426614174000.jpg",
        "originalFileName": "product-image.jpg",
        "objectKey": "profile/123e4567-e89b-12d3-a456-426614174000.jpg",
        "directory": "PROFILE",
        "contentType": "image/jpeg",
        "fileSize": 2048576,
        "fileSizeFormatted": "2.0 MB",
        "permanentUrl": "https://files.nextgate.com/bucket-uuid/profile/123e4567-e89b-12d3-a456-426614174000.jpg",
        "thumbnailUrl": "https://files.nextgate.com/bucket-uuid/profile/123e4567-e89b-12d3-a456-426614174000.jpg",
        "fileExtension": ".jpg",
        "fileType": "IMAGE",
        "isImage": true,
        "isVideo": false,
        "isDocument": false,
        "isAudio": false,
        "width": 1920,
        "height": 1080,
        "dimensions": "1920x1080",
        "checksum": "d41d8cd98f00b204e9800998ecf8427e",
        "uploadedAt": "2025-09-23T10:30:00",
        "uploadedBy": "123e4567-e89b-12d3-a456-426614174000",
        "isPublic": true
      }
    ],
    "totalFiles": 3,
    "successfulUploads": 2,
    "failedUploads": 1,
    "totalSize": 5242880,
    "totalSizeFormatted": "5.0 MB",
    "uploadedAt": "2025-09-23T10:30:00",
    "message": "2 files uploaded successfully, 1 failed",
    "errors": [
      "Failed to upload large-file.mp4: File size exceeds maximum limit of 25MB"
    ]
  }
}

Response Fields:

Field	Description
success	Boolean indicating operation success
httpStatus	HTTP status code as string
message	Overall operation success message
action_time	ISO 8601 timestamp of response generation
data.uploadedFiles	Array of successfully uploaded file details
data.uploadedFiles[].fileName	System-generated unique filename with UUID
data.uploadedFiles[].originalFileName	Original filename provided by user
data.uploadedFiles[].objectKey	Full object path in storage system
data.uploadedFiles[].directory	Directory where file was stored
data.uploadedFiles[].contentType	MIME type of the uploaded file
data.uploadedFiles[].fileSize	File size in bytes
data.uploadedFiles[].fileSizeFormatted	Human-readable file size (e.g., "2.0 MB")
data.uploadedFiles[].permanentUrl	Direct public URL to access the file
data.uploadedFiles[].thumbnailUrl	Thumbnail URL (same as permanentUrl for images)
data.uploadedFiles[].fileExtension	File extension including dot (e.g., ".jpg")
data.uploadedFiles[].fileType	File category (IMAGE, VIDEO, DOCUMENT, AUDIO, OTHER)
data.uploadedFiles[].isImage	Boolean indicating if file is an image
data.uploadedFiles[].isVideo	Boolean indicating if file is a video
data.uploadedFiles[].isDocument	Boolean indicating if file is a document
data.uploadedFiles[].isAudio	Boolean indicating if file is audio
data.uploadedFiles[].width	Image width in pixels (images only)
data.uploadedFiles[].height	Image height in pixels (images only)
data.uploadedFiles[].dimensions	Image dimensions as "WxH" format
data.uploadedFiles[].checksum	MD5 hash of file content for integrity verification
data.uploadedFiles[].uploadedAt	Upload timestamp
data.uploadedFiles[].uploadedBy	Account ID of uploader
data.uploadedFiles[].isPublic	Boolean indicating public accessibility (always true)
data.totalFiles	Total number of files in upload request
data.successfulUploads	Number of successfully uploaded files
data.failedUploads	Number of failed uploads
data.totalSize	Total size of all uploaded files in bytes
data.totalSizeFormatted	Human-readable total size
data.uploadedAt	Overall upload completion timestamp
data.message	Summary message of upload results
data.errors	Array of error messages for failed uploads (null if no errors)

Error Responses:

400 Bad Request: Invalid file format, missing parameters, or validation errors
401 Unauthorized: Missing or invalid JWT token
413 Payload Too Large: File size exceeds 25MB limit
422 Unprocessable Entity: Unsupported file type or directory
500 Internal Server Error: Storage system errors

2. Upload Single File

Purpose: Upload a single file to a specified directory with detailed metadata extraction

Endpoint: POST https://apinexgate.glueauth.com/api/v1/files/upload-single

Access Level: 🔒 Protected (Requires JWT Bearer token)

Authentication: Bearer Token (JWT access token required)

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer {access_token}
Content-Type	string	Yes	Must be "multipart/form-data"

Request Form Data Parameters:

Parameter	Type	Required	Description	Validation
file	file	Yes	Single file to upload	Max 25MB, supported file types only
directory	string	Yes	Target directory for the file	enum: PROFILE, CATEGORIES, SHOPS

Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "File uploaded successfully",
  "action_time": "2025-09-23T10:30:00",
  "data": {
    "fileName": "123e4567-e89b-12d3-a456-426614174000.pdf",
    "originalFileName": "product-catalog.pdf",
    "objectKey": "categories/123e4567-e89b-12d3-a456-426614174000.pdf",
    "directory": "CATEGORIES",
    "contentType": "application/pdf",
    "fileSize": 1048576,
    "fileSizeFormatted": "1.0 MB",
    "permanentUrl": "https://files.nextgate.com/bucket-uuid/categories/123e4567-e89b-12d3-a456-426614174000.pdf",
    "thumbnailUrl": null,
    "fileExtension": ".pdf",
    "fileType": "DOCUMENT",
    "isImage": false,
    "isVideo": false,
    "isDocument": true,
    "isAudio": false,
    "width": null,
    "height": null,
    "dimensions": null,
    "checksum": "5d41402abc4b2a76b9719d911017c592",
    "uploadedAt": "2025-09-23T10:30:00",
    "uploadedBy": "123e4567-e89b-12d3-a456-426614174000",
    "isPublic": true
  }
}

Response Fields:

Field	Description
success	Boolean indicating operation success
httpStatus	HTTP status code as string
message	Success message
action_time	ISO 8601 timestamp of response generation
data	Single FileResponse object with complete file metadata (same structure as uploadedFiles[] items above)

Error Responses:

400 Bad Request: Invalid file, missing parameters, or validation errors
401 Unauthorized: Missing or invalid JWT token
413 Payload Too Large: File size exceeds 25MB limit
422 Unprocessable Entity: Unsupported file type or directory
500 Internal Server Error: Storage system errors

3. Get User Files by Directory

Purpose: Retrieve all files uploaded by the authenticated user in a specific directory

Endpoint: GET https://apinexgate.glueauth.com/api/v1/files/directory/{directory}

Access Level: 🔒 Protected (Requires JWT Bearer token)

Authentication: Bearer Token (JWT access token required)

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer {access_token}
Content-Type	string	Yes	Must be "application/json"

Path Parameters:

Parameter	Type	Required	Description	Validation
directory	string	Yes	Directory to list files from	enum: PROFILE, CATEGORIES, SHOPS

Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Files retrieved successfully",
  "action_time": "2025-09-23T10:30:00",
  "data": [
    {
      "fileName": "123e4567-e89b-12d3-a456-426614174000.jpg",
      "originalFileName": "profile-picture.jpg",
      "objectKey": "profile/123e4567-e89b-12d3-a456-426614174000.jpg",
      "directory": "PROFILE",
      "contentType": "image/jpeg",
      "fileSize": 2048576,
      "fileSizeFormatted": "2.0 MB",
      "permanentUrl": "https://files.nextgate.com/bucket-uuid/profile/123e4567-e89b-12d3-a456-426614174000.jpg",
      "thumbnailUrl": "https://files.nextgate.com/bucket-uuid/profile/123e4567-e89b-12d3-a456-426614174000.jpg",
      "fileExtension": ".jpg",
      "fileType": "IMAGE",
      "isImage": true,
      "isVideo": false,
      "isDocument": false,
      "isAudio": false,
      "width": 1920,
      "height": 1080,
      "dimensions": "1920x1080",
      "uploadedBy": "123e4567-e89b-12d3-a456-426614174000",
      "isPublic": true
    },
    {
      "fileName": "456e7890-e89b-12d3-a456-426614174111.png",
      "originalFileName": "banner-image.png",
      "objectKey": "profile/456e7890-e89b-12d3-a456-426614174111.png",
      "directory": "PROFILE",
      "contentType": "image/png",
      "fileSize": 1524288,
      "fileSizeFormatted": "1.5 MB",
      "permanentUrl": "https://files.nextgate.com/bucket-uuid/profile/456e7890-e89b-12d3-a456-426614174111.png",
      "thumbnailUrl": "https://files.nextgate.com/bucket-uuid/profile/456e7890-e89b-12d3-a456-426614174111.png",
      "fileExtension": ".png",
      "fileType": "IMAGE",
      "isImage": true,
      "isVideo": false,
      "isDocument": false,
      "isAudio": false,
      "width": 1600,
      "height": 900,
      "dimensions": "1600x900",
      "uploadedBy": "123e4567-e89b-12d3-a456-426614174000",
      "isPublic": true
    }
  ]
}

Response Fields:

Field	Description
success	Boolean indicating operation success
httpStatus	HTTP status code as string
message	Success message
action_time	ISO 8601 timestamp of response generation
data	Array of FileResponse objects for all files in the specified directory

Error Responses:

400 Bad Request: Invalid directory parameter
401 Unauthorized: Missing or invalid JWT token
404 Not Found: Directory not found or user not found
500 Internal Server Error: Storage system errors

4. Delete File

Purpose: Delete a specific file uploaded by the authenticated user

Endpoint: DELETE https://apinexgate.glueauth.com/api/v1/files/{objectKey}

Access Level: 🔒 Protected (Requires JWT Bearer token)

Authentication: Bearer Token (JWT access token required)

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer {access_token}
Content-Type	string	Yes	Must be "application/json"

Path Parameters:

Parameter	Type	Required	Description	Validation
objectKey	string	Yes	Full object key/path of the file to delete	Must be a valid object key from user's files

Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "File deleted successfully",
  "action_time": "2025-09-23T10:30:00",
  "data": null
}

Response Fields:

Field	Description
success	Boolean indicating operation success
httpStatus	HTTP status code as string
message	Success message confirming deletion
action_time	ISO 8601 timestamp of response generation
data	Always null for delete operations

Error Responses:

400 Bad Request: Invalid object key format
401 Unauthorized: Missing or invalid JWT token
404 Not Found: File not found or user not found
403 Forbidden: Attempting to delete file not owned by user
500 Internal Server Error: Storage system errors

Quick Reference Guide

File Directory Types

PROFILE: User profile images, avatars, and personal media
CATEGORIES: Category images, banners, and related media
SHOPS: Shop-related images, logos, and promotional materials

Supported File Types

Images: JPEG, JPG, PNG, GIF, WebP, BMP, SVG
Videos: MP4, AVI, MOV, WMV, FLV, WebM, MKV
Documents: PDF, DOC, DOCX, TXT, XLS
Audio: MP3, WAV, OGG, AAC

File Size and Limits

Maximum file size: 25MB per file
File naming: Original names preserved, unique UUIDs generated for storage
Public access: All uploaded files are publicly accessible via direct URLs
Checksums: MD5 hashes calculated for file integrity verification

Common HTTP Status Codes

200 OK: Successful GET/DELETE request
201 Created: Successful POST request (file upload)
400 Bad Request: Invalid request data or file validation errors
401 Unauthorized: Authentication required/failed
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
413 Payload Too Large: File size exceeds limit
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error

Authentication Types

Bearer Token: Include Authorization: Bearer your_access_token in headers
Form Data: Use multipart/form-data for file uploads
JSON: Use application/json for other requests

Data Format Standards

Dates: Use ISO 8601 format (2025-09-23T10:30:00Z)
File sizes: Provided in bytes and human-readable format
UUIDs: Standard UUID format for all identifiers
URLs: Full HTTPS URLs for file access

Shop Categories Management

Shop Management

Shop Rating

Shop Review

Product Management

Cart Management

Wishlist Management

Wallet

Transaction History

Installment Purchase - Customer Endpoints

Installment Purchase - Public & Plan Endpoints

Installment Plan Management - Admin/Shop Endpoints

File Management Service

Endpoints

1. Upload Multiple Files

2. Upload Single File

3. Get User Files by Directory

4. Delete File

Quick Reference Guide

File Directory Types

Supported File Types

File Size and Limits

Common HTTP Status Codes

Authentication Types

Data Format Standards