Spaces:

lucifer925
/

streamflix-api

Runtime error

App Files Files

streamflix-api / src /shared /modules /upload /uploadcare /UPLOADCARE_SETUP.md

Akshar2325

docs(uploadcare): generalize setup guide examples

34dcb32 8 months ago

preview code

Raw

History Blame

10.1 kB

🚀 Uploadcare Integration Guide

📋 Table of Contents

Overview
Setup Instructions
API Endpoints
Testing with Postman
Viewing Uploaded Files
Examples

🎯 Overview

This integration uses Uploadcare with secure signed uploads enabled. We have 3 separate projects configured:

Project	File Type	Public Key	Use Case
Streamflix Backend Image	`IMAGE`	`8460d7f9bdsc79569e82cec`	Images (JPG, PNG, GIF, etc.)
Streamflix Backend Videos	`VIDEO`	`d92b2e314264sc80583f6b`	Videos (MP4, AVI, MOV, etc.)
Streamflix Backend Documents	`DOCUMENT`	`70e723d3652esxs3ec1f7a2`	Documents (PDF, DOC, TXT, etc.)

Key Features:

✅ Secure signed uploads (prevents unauthorized uploads)
✅ Separate projects for different file types
✅ Automatic CDN delivery via ucarecdn.com
✅ Delete files by URL

🛠️ Setup Instructions

1. Environment Variables

Already configured in .env:

# Uploadcare Storage Configuration
UPLOADCARE_IMAGE_PUBLIC_KEY=your_image_project_public_key
UPLOADCARE_IMAGE_PRIVATE_KEY=your_image_project_private_key

UPLOADCARE_VIDEO_PUBLIC_KEY=your_video_project_public_key
UPLOADCARE_VIDEO_PRIVATE_KEY=your_video_project_private_key

UPLOADCARE_DOCUMENT_PUBLIC_KEY=your_document_project_public_key
UPLOADCARE_DOCUMENT_PRIVATE_KEY=your_document_project_private_key

2. Enable Signed Uploads

In your Uploadcare dashboard for each project:

Go to Settings → Security
Enable "Secure uploads" toggle

3. Start Your Server

npm run start:dev

Endpoints available at:

http://localhost:5119/uploadcare/signed-upload
http://localhost:5119/uploadcare/by-url

📡 API Endpoints

1. Get Signed Upload Parameters

Endpoint: GET /uploadcare/signed-upload

Query Parameters:

type (optional): IMAGE, VIDEO, or DOCUMENT (default: IMAGE)

Example:

GET http://localhost:5119/uploadcare/signed-upload?type=IMAGE

Response:

{
  "publicKey": "8460d7f9b79569e82cecssas",
  "expire": 1703789456,
  "signature": "a1b2c3d4e5f6g7h8ias9j0",
  "uploadUrl": "https://upload.uploadcare.com/base/"
}

2. Get File Information by UUID

Endpoint: GET /uploadcare/file-info

Get the actual CDN URL and file details using the file UUID.

Query Parameters:

uuid (required): File UUID
type (optional): IMAGE, VIDEO, or DOCUMENT (default: IMAGE)

Example:

GET http://localhost:5119/uploadcare/file-info?uuid=f95cdfd1-25a5-4416-ae5b-c773a7af4958&type=IMAGE

Response:

{
  "uuid": "f95cdfd1-25a5-4416-ae5b-c773a7af4958",
  "filename": "Terinajarokekaran4.jpg",
  "size": 245678,
  "mimeType": "image/jpeg",
  "url": "https://6880sokg5s.ucarecd.net/f95cdfd1-25a5-4416-ae5b-c773a7af4958/",
  "originalFileUrl": "https://6880sokg5s.ucarecd.net/f95cdfd1-25a5-4416-ae5b-c773a7af4958/Terinajarokekaran4.jpg",
  "isImage": true,
  "isReady": true,
  "datetimeStored": "2023-12-28T10:30:00Z",
  "datetimeUploaded": "2023-12-28T10:29:55Z"
}

Note: Use the url or originalFileUrl from the response to view/access the file in the browser.

3. Delete File by URL or UUID

Endpoint: DELETE /uploadcare/by-url

Deletes a file using either the full CDN URL or just the UUID.

Query Parameters:

url (required): Full CDN URL or UUID
type (optional): IMAGE, VIDEO, or DOCUMENT (default: IMAGE)

Examples:

Delete by URL:

DELETE http://localhost:5119/uploadcare/by-url?url=https://6880sokg5s.ucarecd.net/f95cdfd1-25a5-4416-ae5b-c773a7af4958/&type=IMAGE

Delete by UUID:

DELETE http://localhost:5119/uploadcare/by-url?url=f95cdfd1-25a5-4416-ae5b-c773a7af4958&type=IMAGE

Response:

{
  "message": "File deleted successfully",
  "urlOrUuid": "https://6880sokg5s.ucarecd.net/f95cdfd1-25a5-4416-ae5b-c773a7af4958/",
  "fileUuid": "f95cdfd1-25a5-4416-ae5b-c7sxs73a7af4958"
}

🧪 Testing with Postman

Step 1: Get Upload Signature

Request:

GET http://localhost:5119/uploadcare/signed-upload?type=IMAGE

Response:

{
  "publicKey": "8460d7f9b79569e8sxs2cec",
  "expire": 1703789456,
  "signature": "abc12xs3def456",
  "uploadUrl": "https://upload.uploadcare.com/base/"
}

Save the response values!

Step 2: Upload File to Uploadcare

Request:

POST https://upload.uploadcare.com/base/
Content-Type: multipart/form-data

Form Data:

Key	Value
`UPLOADCARE_PUB_KEY`	`8460d7f9b79569e82cec` (from step 1)
`expire`	`1703789456` (from step 1)
`signature`	`abc123def456` (from step 1)
`file`	Select your file

Response:

{
  "file": "12345678-1234-1234-1234-123456789abc"
}

The file value is your File UUID! Save it for the next step.

Step 3: Get File Information

Use the UUID from Step 2 to get the actual CDN URL:

Request:

GET http://localhost:5119/uploadcare/file-info?uuid=12345678-1234-1234-1234-123456789abc&type=IMAGE

Response:

{
  "uuid": "12345678-1234-1234-1234-123456789abc",
  "filename": "my-image.jpg",
  "size": 245678,
  "mimeType": "image/jpeg",
  "url": "https://6880sokg5s.ucarecd.net/12345678-1234-1234-1234-123456789abc/",
  "originalFileUrl": "https://6880sokg5s.ucarecd.net/12345678-1234-1234-1234-123456789abc/my-image.jpg",
  "isImage": true,
  "isReady": true,
  "datetimeStored": "2023-12-28T10:30:00Z",
  "datetimeUploaded": "2023-12-28T10:29:55Z"
}

Step 4: View Uploaded File in Browser

Copy the originalFileUrl from Step 3 and paste it in your browser:

https://6880sokg5s.ucarecd.net/12345678-1234-1234-1234-123456789abc/my-image.jpg

That's it! Your file is now uploaded and accessible via CDN.

Step 5: Delete File (Optional)

Request:

DELETE http://localhost:5119/uploadcare/by-url?url=https://6880sokg5s.ucarecd.net/12345678-1234-1234-1234-123456789abc/&type=IMAGE

Or delete using just the UUID:

DELETE http://localhost:5119/uploadcare/by-url?url=12345678-1234-1234-1234-123456789abc&type=IMAGE

Response:

{
  "message": "File deleted successfully",
  "urlOrUuid": "https://6880sokg5s.ucarecd.net/12345678-1234-1234-1234-123456789abc/",
  "fileUuid": "12345678-1234-1234-1234-123456789abc"
}

📝 Complete Examples

Example 1: Upload an Image

1. Get Signature:

GET http://localhost:5119/uploadcare/signed-upload?type=IMAGE

2. Upload:

POST https://upload.uploadcare.com/base/

Form Data:
- UPLOADCARE_PUB_KEY: 8460d7f9b79569e82cec
- expire: 1703789456
- signature: xyz789abc123
- file: [your-image.jpg]

3. View:

https://ucarecdn.com/a1b2c3d4-e5f6-7890-abcd-ef1234567890/

4. Delete:

DELETE http://localhost:5119/uploadcare/by-url?url=https://ucarecdn.com/a1b2c3d4-e5f6-7890-abcd-ef1234567890/&type=IMAGE

Example 2: Upload a Video

1. Get Signature:

GET http://localhost:5119/uploadcare/signed-upload?type=VIDEO

2. Upload:

POST https://upload.uploadcare.com/base/

Form Data:
- UPLOADCARE_PUB_KEY: d92b2e31426480583f6b
- expire: 1703796656
- signature: def456ghi789
- file: [your-video.mp4]

3. View:

https://ucarecdn.com/v1d2e3o4-5678-90ab-cdef-1234567890ab/

Example 3: Upload a PDF Document

1. Get Signature:

GET http://localhost:5119/uploadcare/signed-upload?type=DOCUMENT

2. Upload:

POST https://upload.uploadcare.com/base/

Form Data:
- UPLOADCARE_PUB_KEY: 70e723d3652e3ec1f7a2
- expire: 1703789456
- signature: jkl012mno345
- file: [document.pdf]

3. View:

https://ucarecdn.com/d0c1u2m3-4567-89ab-cdef-0123456789ab/

🌐 CDN URL Formats

Direct Access

https://ucarecdn.com/{FILE_UUID}/

With Filename

https://ucarecdn.com/{FILE_UUID}/filename.jpg

Image Transformations

# Resize to 400px width
https://ucarecdn.com/{UUID}/-/resize/400x/

# Preview (crop and resize)
https://ucarecdn.com/{UUID}/-/preview/800x600/

# Smart quality optimization
https://ucarecdn.com/{UUID}/-/quality/smart/

# Convert to WebP
https://ucarecdn.com/{UUID}/-/format/webp/

# Chain operations
https://ucarecdn.com/{UUID}/-/resize/400x/-/quality/smart/-/format/webp/

🔒 Security Notes

Signed Uploads: All uploads require a valid signature from the backend
Expiration: Signatures expire after 1 hour by default
Private Keys: Never expose private keys in frontend code
Separate Projects: Each file type uses a different project

📊 Uploadcare Dashboard

View your uploaded files:

Images: https://app.uploadcare.com/projects/8460d7f9b79569e82cec/
Videos: https://app.uploadcare.com/projects/d92b2e31426480583f6b/
Documents: https://app.uploadcare.com/projects/70e723d3652e3ec1f7a2/

🐛 Troubleshooting

Upload fails with "Signature is invalid"

Ensure you're using the correct signature from the backend
Check that the signature hasn't expired
Verify you're using the correct public key

File not found after upload

Wait a few seconds - processing may take time
Check the Uploadcare dashboard
Verify the file UUID is correct

Cannot delete file

Ensure the URL format is correct
Verify the file exists in the correct project
Check that you're using the correct file type parameter

✅ Quick Testing Checklist

Get signature from backend (GET /uploadcare/signed-upload?type=IMAGE)
Upload file to Uploadcare with signature
Verify file UUID in response
Open CDN URL in browser
Delete file by URL (optional)

Happy Uploading! 🎉