File Upload API

The File Upload API is a crucial part of the FileVerbs system, allowing users to upload files securely before initiating any conversion jobs. The uploaded file is stored in Azure Blob Storage, and a unique fileId is returned, which is then used for job requests. This process supports a wide range of file types and is designed to handle large-scale uploads.

Features of the File Upload API

• Secure Uploads: Files are uploaded directly to Azure Blob Storage, ensuring data is safely stored.
• Scalable: The API is designed to handle multiple concurrent uploads, making it ideal for large-scale file processing.
• Real-time Feedback: Receive immediate status updates for each file upload request.
• Flexible Input: Supports a wide range of file types and allows for custom descriptions to be attached to each upload.

Upload a File

Upload a file using the POST method. This request requires a file to be included in the form data, alongside the file type and an optional description.

Endpoint:

POST /api/v1/fileuploads/upload

Authorization:

Requires a valid Bearer token in the header.

Request Example (cURL):

curl -X POST https://api.fileverbs.com/api/v1/fileuploads/upload \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-F "file=/path/to/your/file.pdf" \
-F "fileType=pdf" \
-F "description=Sample file upload"
                        

Request Payload:

{
  "file": "file.pdf",
  "fileType": "pdf",
  "description": "Sample file upload"
}
                        

Response:

{
  "status": "File uploaded successfully",
  "fileId": "5f8b26e9e2c9a8a739b2bb44"
}
                        

Retrieve All Uploaded Files

Fetch a list of all files uploaded by the authenticated user.

Endpoint:

GET /api/v1/fileuploads

Response Example:

[
  {
    "fileId": "5f8b26e9e2c9a8a739b2bb44",
    "fileName": "sample.pdf",
    "fileType": "pdf",
    "description": "Sample file upload",
    "uploadDate": "2023-10-09T12:34:56Z"
  },
  {
    "fileId": "5f8b26e9e2c9a8a739b2bb45",
    "fileName": "document.docx",
    "fileType": "docx",
    "description": "Document upload",
    "uploadDate": "2023-10-08T11:22:33Z"
  }
]
                        

Download a File

Download a previously uploaded file using its fileId.

Endpoint:

GET /api/v1/fileuploads/{fileId}/download

Example:

curl -X GET https://api.fileverbs.com/api/v1/fileuploads/5f8b26e9e2c9a8a739b2bb44/download \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." -o downloaded_file.pdf
                        

Delete an Uploaded File

Soft-delete an uploaded file using its fileId. The file remains in storage but is marked as inactive and won't appear in active file listings.

Endpoint:

DELETE /api/v1/fileuploads/{fileId}

Response Example:

{
  "status": "File deleted successfully"
}
                        

Error Handling

• 400 Bad Request: Indicates issues such as missing file or incorrect file format.
• 401 Unauthorized: Returned if the Bearer token is invalid or missing.
• 404 Not Found: Returned if the specified fileId does not exist or is not associated with the user.
• 500 Internal Server Error: Indicates server-side issues. Retry the request or contact support.

Best Practices for File Uploads

• Chunked Uploads: For very large files, consider implementing a chunked upload strategy to enhance performance.
• File Type Validation: Ensure that the fileType parameter matches the actual file format to avoid conversion issues later.
• Store fileId Securely: Store the fileId securely as it will be used for further processing in job requests.

Example Workflow

1. Upload a PDF using the File Upload API.
2. Store the returned fileId for job creation.
3. Create a job using the JobRequest API, referencing the fileId.
4. Track the job status until completion.
5. Download the converted file once the job is done.

By following this guide, users can efficiently manage their file uploads and integrate them seamlessly with the FileVerbs API for further processing and conversions.