API Documentation

Complete API reference for the FeelyFeely CDN service.

Base URL

Production: https://cdn.feelyfeely.com
Development: http://localhost:5065

Authentication

The CDN uses Keycloak for authentication. Include the authorization header for protected endpoints:

Authorization: Bearer <your-jwt-token>

Image Endpoints

1. General User Assets

Retrieve and process user-uploaded assets with dynamic operations.

GET /image/<bucket>/<uuid>/<operation>/<path:s3_key>

Parameters

Parameter	Type	Description	Example
bucket	string	DigitalOcean Spaces bucket name	ff.user.assets
uuid	string	Unique identifier for the asset	12345-67890-abcdef
operation	string	Image processing operation	medium, thumbnail, etc.
s3_key	string	File path in the bucket	profile/avatar.jpg

Example Request

curl -X GET "https://cdn.feelyfeely.com/image/ff.user.assets/12345-67890/medium/profile/avatar.jpg"

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 45678

[Binary image data with watermark]

2. Mobile Device Photos

Access photos from mobile devices with automatic processing.

GET /image/mobiledevice/<path:s3_key>

Parameters

Parameter	Type	Description	Example
s3_key	string	Full path to the image	devices/iphone/photos/2024/01/photo1.jpg

Example Request

curl -X GET "https://cdn.feelyfeely.com/image/mobiledevice/devices/iphone12/medium/photos/2024/photo1.jpg"

3. Vehicle Photos

Retrieve vehicle-related images with processing.

GET /image/vehicle/<path:s3_key>

Parameters

Parameter	Type	Description	Example
s3_key	string	Full path to the vehicle image	cars/sedan/exterior/front.jpg

Example Request

curl -X GET "https://cdn.feelyfeely.com/image/vehicle/cars/toyota/camry/2024/thumbnail/exterior.jpg"

Image Operations

Available Operations

Operation	Dimensions	Smart Crop	Use Case
thumbnail	150×150	✓	Profile pictures, avatars
small	320×240	✓	Small previews, thumbnails
medium	640×480	✓	Standard web images
large	1024×768	✓	High-quality displays
wide	1280×720	✓	Widescreen displays
portrait	800×1200	✓	Portrait orientation
landscape	1200×800	✓	Landscape orientation
square	600×600	✓	Square format images
hero	1920×1080	✓	Banner/hero images
full	2560×1440	✓	Full HD displays
profile	400×400	✓	Profile photos
slideshow	3000×1687	✓	Presentation slides

Quality Settings

The CDN automatically applies optimal quality settings:

Quality	Description	Use Case
auto	Service-optimized	Default for most images
normal	Standard quality	1× pixel density displays
better	Enhanced quality	Small detailed previews (~125% size)
best	Near-pristine	Artwork, professional photos (~170% size)
lighter	Bandwidth optimized	Large images (~80% size)
lightest	Maximum compression	High-DPI displays (~50% size)

Image Processing Flow

1. Request Flow

graph TD
    A[Client Request] --> B{Image Exists?}
    B -->|Yes| C[Fetch from Spaces]
    B -->|No| D[Fetch Original]
    D --> E[Upload to Uploadcare]
    E --> F[Apply Operations]
    F --> G[Store Processed Image]
    C --> H[Apply Watermark]
    G --> H
    H --> I[Return to Client]

2. Automatic Features

• Smart Cropping: Preserves important image areas
• Format Optimization: Automatic format selection (WebP, JPEG, PNG)
• Quality Adjustment: Dynamic quality based on image content
• Watermark Embedding: Real-time watermark application based on image brightness
• Caching: Processed images are cached for faster subsequent access

Error Responses

HTTP Status Codes

Code	Description	Response Body
200	Success	Image binary data
400	Bad Request	{"error": "Invalid parameters"}
403	Forbidden	{"error": "Access denied"}
404	Not Found	{"error": "Image not found"}
500	Server Error	{"error": "Internal server error"}

Error Examples

404 - Image Not Found

{
  "status": 404,
  "error": "file not found",
  "message": "The requested image does not exist"
}

400 - Unsupported Operation

{
  "status": 400,
  "error": "unsupported operation",
  "message": "The requested operation is not supported"
}

Rate Limiting

The CDN implements rate limiting to ensure service quality:

• Requests per minute: 1000 per IP
• Concurrent requests: 50 per IP
• Daily bandwidth: 10GB per IP (adjustable)

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1640995200

Caching

Client-Side Caching

Images include appropriate cache headers:

Cache-Control: public, max-age=31536000
ETag: "abc123def456"
Last-Modified: Wed, 21 May 2024 15:30:00 GMT

CDN Caching

• Original images: Cached indefinitely
• Processed images: Cached for 1 year
• Watermarked images: Generated in real-time

Advanced Usage

URL Parameters

Add query parameters for additional control:

# Force refresh (bypass cache)
/image/bucket/uuid/medium/photo.jpg?refresh=true

# Custom quality
/image/bucket/uuid/medium/photo.jpg?quality=best

# Disable watermark (if authorized)
/image/bucket/uuid/medium/photo.jpg?nowatermark=true

Batch Operations

For multiple images, use the batch endpoint:

POST /batch/images
Content-Type: application/json

{
  "images": [
    {
      "bucket": "ff.user.assets",
      "uuid": "12345",
      "operation": "thumbnail",
      "s3_key": "photo1.jpg"
    },
    {
      "bucket": "ff.user.assets", 
      "uuid": "12346",
      "operation": "medium",
      "s3_key": "photo2.jpg"
    }
  ]
}

SDK Examples

JavaScript/Node.js

const FFCDN = require('@feelyfeely/cdn-sdk');

const cdn = new FFCDN({
  baseURL: 'https://cdn.feelyfeely.com',
  apiKey: 'your-api-key'
});

// Get processed image URL
const imageUrl = cdn.getImageUrl({
  bucket: 'ff.user.assets',
  uuid: '12345',
  operation: 'medium',
  s3Key: 'profile/avatar.jpg'
});

// Preload multiple images
const images = await cdn.preloadImages([
  { uuid: '12345', operation: 'thumbnail', s3Key: 'photo1.jpg' },
  { uuid: '12346', operation: 'medium', s3Key: 'photo2.jpg' }
]);

Python

from feelyfeely_cdn import FFCDN

cdn = FFCDN(
    base_url='https://cdn.feelyfeely.com',
    api_key='your-api-key'
)

# Get image URL
image_url = cdn.get_image_url(
    bucket='ff.user.assets',
    uuid='12345',
    operation='medium',
    s3_key='profile/avatar.jpg'
)

# Download image
image_data = cdn.download_image(
    uuid='12345',
    operation='thumbnail',
    s3_key='photo.jpg'
)

cURL Examples

# Basic image request
curl -H "Authorization: Bearer <token>" \
     "https://cdn.feelyfeely.com/image/ff.user.assets/12345/medium/photo.jpg"

# Mobile device photo
curl "https://cdn.feelyfeely.com/image/mobiledevice/devices/iphone/photos/2024/photo.jpg"

# Vehicle photo with custom quality
curl "https://cdn.feelyfeely.com/image/vehicle/cars/sedan/exterior.jpg?quality=best"

Performance Considerations

Optimization Tips

1. Choose appropriate operations: Use smaller operations for thumbnails
2. Leverage caching: Images are cached, subsequent requests are faster
3. Use CDN domains: Multiple domains for parallel downloads
4. Preload critical images: Use batch endpoints for multiple images

Best Practices

1. Progressive loading: Load thumbnails first, then higher resolutions
2. Responsive images: Request appropriate sizes for different devices
3. Error handling: Always handle 404s and fallback to default images
4. Monitor usage: Track bandwidth and request patterns

Monitoring & Analytics

Metrics Available

• Request count and response times
• Bandwidth usage by operation
• Cache hit/miss ratios
• Error rates by endpoint
• Popular image sizes and operations

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 86400,
  "services": {
    "mysql": "connected",
    "mongodb": "connected",
    "spaces": "connected",
    "uploadcare": "connected"
  }
}

Troubleshooting

Common Issues

1. Slow Image Loading

   • Check if original image exists
   • Verify Uploadcare processing time
   • Monitor DigitalOcean Spaces latency

2. Images Not Found

   • Verify bucket permissions
   • Check S3 key path
   • Confirm upload completion

3. Quality Issues

   • Review operation settings
   • Check Uploadcare processing logs
   • Verify source image quality

Support

For API support:

• Email: [email protected]
• Documentation: Full documentation available
• Status Page: https://status.feelyfeely.com