pacnpal/thrillwiki_django_no_react
1
1
Fork 0
mirror of https://github.com/pacnpal/thrillwiki_django_no_react.git synced 2025-12-20 06:51:08 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
47c435d2f51353b60f90ea50eb9f59dde88df5da
thrillwiki_django_no_react/docs/cloudflare_images_integration.md
pacnpal f3c59ad6ff remove backend
2025-09-21 20:19:12 -04:00

19 KiB
Raw Blame History

Cloudflare Images Integration

Overview

This document describes the complete integration of django-cloudflare-images into the ThrillWiki project for both rides and parks models, including full API schema metadata support.

Implementation Summary

1. Models Updated

Rides Models (backend/apps/rides/models/media.py)

  • RidePhoto.image: Changed from models.ImageField to CloudflareImagesField(variant="public")
  • Added proper Meta class inheritance from TrackedModel.Meta
  • Maintains all existing functionality while leveraging Cloudflare Images

Parks Models (backend/apps/parks/models/media.py)

  • ParkPhoto.image: Changed from models.ImageField to CloudflareImagesField(variant="public")
  • Added proper Meta class inheritance from TrackedModel.Meta
  • Maintains all existing functionality while leveraging Cloudflare Images

2. API Serializers Enhanced

Rides API (backend/apps/api/v1/rides/serializers.py)

  • RidePhotoOutputSerializer: Enhanced with Cloudflare Images support
    • Added image_url field: Full URL to the Cloudflare Images asset
    • Added image_variants field: Dictionary of available image variants with URLs
    • Proper DRF Spectacular schema decorations with examples
    • Maintains backward compatibility

Parks API (backend/apps/api/v1/parks/serializers.py)

  • ParkPhotoOutputSerializer: Enhanced with Cloudflare Images support
    • Added image_url field: Full URL to the Cloudflare Images asset
    • Added image_variants field: Dictionary of available image variants with URLs
    • Proper DRF Spectacular schema decorations with examples
    • Maintains backward compatibility

3. Schema Metadata

Both serializers include comprehensive OpenAPI schema metadata:

  • Field Documentation: All new fields have detailed help text and type information
  • Examples: Complete example responses showing Cloudflare Images URLs and variants
  • Variants: Documented image variants (thumbnail, medium, large, public) with descriptions

4. Database Migrations

  • rides.0008_cloudflare_images_integration: Updates RidePhoto.image field
  • parks.0009_cloudflare_images_integration: Updates ParkPhoto.image field
  • Migrations applied successfully with no data loss

Configuration

The project already has Cloudflare Images configured in backend/config/django/base.py:

# Cloudflare Images Settings
STORAGES = {
    "default": {
        "BACKEND": "cloudflare_images.storage.CloudflareImagesStorage",
    },
    # ... other storage configs
}

CLOUDFLARE_IMAGES_ACCOUNT_ID = config("CLOUDFLARE_IMAGES_ACCOUNT_ID")
CLOUDFLARE_IMAGES_API_TOKEN = config("CLOUDFLARE_IMAGES_API_TOKEN") 
CLOUDFLARE_IMAGES_ACCOUNT_HASH = config("CLOUDFLARE_IMAGES_ACCOUNT_HASH")
CLOUDFLARE_IMAGES_DOMAIN = config("CLOUDFLARE_IMAGES_DOMAIN", default="imagedelivery.net")

API Response Format

Enhanced Photo Response

Both ride and park photo endpoints now return:

{
  "id": 123,
  "image": "https://imagedelivery.net/account-hash/image-id/public",
  "image_url": "https://imagedelivery.net/account-hash/image-id/public", 
  "image_variants": {
    "thumbnail": "https://imagedelivery.net/account-hash/image-id/thumbnail",
    "medium": "https://imagedelivery.net/account-hash/image-id/medium",
    "large": "https://imagedelivery.net/account-hash/image-id/large",
    "public": "https://imagedelivery.net/account-hash/image-id/public"
  },
  "caption": "Photo caption",
  "alt_text": "Alt text for accessibility",
  "is_primary": true,
  "is_approved": true,
  "photo_type": "exterior", // rides only
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z",
  "date_taken": "2023-01-01T10:00:00Z",
  "uploaded_by_username": "photographer123",
  "file_size": 2048576,
  "dimensions": [1920, 1080],
  "ride_slug": "steel-vengeance", // rides only
  "ride_name": "Steel Vengeance", // rides only  
  "park_slug": "cedar-point",
  "park_name": "Cedar Point"
}

Image Variants

The integration provides these standard variants:

  • thumbnail: 150x150px - Perfect for list views and previews
  • medium: 500x500px - Good for modal previews and medium displays
  • large: 1200x1200px - High quality for detailed views
  • public: Original size - Full resolution image

Benefits

  1. Performance: Cloudflare's global CDN ensures fast image delivery
  2. Optimization: Automatic image optimization and format conversion
  3. Variants: Multiple image sizes generated automatically
  4. Scalability: No local storage requirements
  5. API Documentation: Complete OpenAPI schema with examples
  6. Backward Compatibility: Existing API consumers continue to work
  7. Entity Validation: Photos are always associated with valid rides or parks
  8. Data Integrity: Prevents orphaned photos without parent entities
  9. Automatic Photo Inclusion: Photos are automatically included when displaying rides and parks
  10. Primary Photo Support: Easy access to the main photo for each entity

Automatic Photo Integration

Ride Detail Responses

When fetching ride details via GET /api/v1/rides/{id}/, the response automatically includes:

  • photos: Array of up to 10 approved photos with full Cloudflare Images variants
  • primary_photo: The designated primary photo for the ride (if available)
{
  "id": 1,
  "name": "Steel Vengeance",
  "slug": "steel-vengeance",
  "photos": [
    {
      "id": 123,
      "image_url": "https://imagedelivery.net/account-hash/abc123def456/public",
      "image_variants": {
        "thumbnail": "https://imagedelivery.net/account-hash/abc123def456/thumbnail",
        "medium": "https://imagedelivery.net/account-hash/abc123def456/medium",
        "large": "https://imagedelivery.net/account-hash/abc123def456/large",
        "public": "https://imagedelivery.net/account-hash/abc123def456/public"
      },
      "caption": "Amazing roller coaster photo",
      "alt_text": "Steel roller coaster with multiple inversions",
      "is_primary": true,
      "photo_type": "exterior"
    }
  ],
  "primary_photo": {
    "id": 123,
    "image_url": "https://imagedelivery.net/account-hash/abc123def456/public",
    "image_variants": {
      "thumbnail": "https://imagedelivery.net/account-hash/abc123def456/thumbnail",
      "medium": "https://imagedelivery.net/account-hash/abc123def456/medium",
      "large": "https://imagedelivery.net/account-hash/abc123def456/large",
      "public": "https://imagedelivery.net/account-hash/abc123def456/public"
    },
    "caption": "Amazing roller coaster photo",
    "alt_text": "Steel roller coaster with multiple inversions",
    "photo_type": "exterior"
  }
}

Park Detail Responses

When fetching park details via GET /api/v1/parks/{id}/, the response automatically includes:

  • photos: Array of up to 10 approved photos with full Cloudflare Images variants
  • primary_photo: The designated primary photo for the park (if available)
{
  "id": 1,
  "name": "Cedar Point",
  "slug": "cedar-point",
  "photos": [
    {
      "id": 456,
      "image_url": "https://imagedelivery.net/account-hash/def789ghi012/public",
      "image_variants": {
        "thumbnail": "https://imagedelivery.net/account-hash/def789ghi012/thumbnail",
        "medium": "https://imagedelivery.net/account-hash/def789ghi012/medium",
        "large": "https://imagedelivery.net/account-hash/def789ghi012/large",
        "public": "https://imagedelivery.net/account-hash/def789ghi012/public"
      },
      "caption": "Beautiful park entrance",
      "alt_text": "Cedar Point main entrance with flags",
      "is_primary": true
    }
  ],
  "primary_photo": {
    "id": 456,
    "image_url": "https://imagedelivery.net/account-hash/def789ghi012/public",
    "image_variants": {
      "thumbnail": "https://imagedelivery.net/account-hash/def789ghi012/thumbnail",
      "medium": "https://imagedelivery.net/account-hash/def789ghi012/medium",
      "large": "https://imagedelivery.net/account-hash/def789ghi012/large",
      "public": "https://imagedelivery.net/account-hash/def789ghi012/public"
    },
    "caption": "Beautiful park entrance",
    "alt_text": "Cedar Point main entrance with flags"
  }
}

Photo Filtering

  • Only approved photos (is_approved=True) are included in entity responses
  • Photos are ordered by primary status first, then by creation date (newest first)
  • Limited to 10 photos maximum per entity to maintain response performance
  • Primary photo is provided separately for easy access to the main image

Testing

The implementation has been verified:

  • ✅ Models successfully use CloudflareImagesField
  • ✅ Migrations applied without issues
  • ✅ Serializers import and function correctly
  • ✅ Schema metadata properly configured
  • ✅ Photos automatically included in ride and park detail responses
  • ✅ Primary photo selection working correctly

Upload Examples

1. Upload Ride Photo via API

Endpoint: POST /api/v1/rides/{ride_id}/photos/

Requirements:

  • Valid JWT authentication token
  • Existing ride with the specified ride_id
  • Image file in supported format (JPEG, PNG, WebP, etc.)

Headers:

Authorization: Bearer <your_jwt_token>
Content-Type: multipart/form-data

cURL Example:

curl -X POST "https://your-domain.com/api/v1/rides/123/photos/" \
  -H "Authorization: Bearer your_jwt_token_here" \
  -F "image=@/path/to/your/photo.jpg" \
  -F "caption=Amazing steel coaster shot" \
  -F "alt_text=Steel Vengeance coaster with riders" \
  -F "photo_type=exterior" \
  -F "is_primary=false"

Error Response (Non-existent Ride):

{
  "detail": "Ride not found"
}

Python Example:

import requests

url = "https://your-domain.com/api/v1/rides/123/photos/"
headers = {"Authorization": "Bearer your_jwt_token_here"}

with open("/path/to/your/photo.jpg", "rb") as image_file:
    files = {"image": image_file}
    data = {
        "caption": "Amazing steel coaster shot",
        "alt_text": "Steel Vengeance coaster with riders",
        "photo_type": "exterior",
        "is_primary": False
    }
    
    response = requests.post(url, headers=headers, files=files, data=data)
    print(response.json())

JavaScript Example:

const formData = new FormData();
formData.append('image', fileInput.files[0]);
formData.append('caption', 'Amazing steel coaster shot');
formData.append('alt_text', 'Steel Vengeance coaster with riders');
formData.append('photo_type', 'exterior');
formData.append('is_primary', 'false');

fetch('/api/v1/rides/123/photos/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_jwt_token_here'
  },
  body: formData
})
.then(response => response.json())
.then(data => console.log(data));

2. Upload Park Photo via API

Endpoint: POST /api/v1/parks/{park_id}/photos/

Requirements:

  • Valid JWT authentication token
  • Existing park with the specified park_id
  • Image file in supported format (JPEG, PNG, WebP, etc.)

cURL Example:

curl -X POST "https://your-domain.com/api/v1/parks/456/photos/" \
  -H "Authorization: Bearer your_jwt_token_here" \
  -F "image=@/path/to/park-entrance.jpg" \
  -F "caption=Beautiful park entrance" \
  -F "alt_text=Cedar Point main entrance with flags" \
  -F "is_primary=true"

Error Response (Non-existent Park):

{
  "detail": "Park not found"
}

3. Upload Response Format

Both endpoints return the same enhanced format with Cloudflare Images integration:

{
  "id": 789,
  "image": "https://imagedelivery.net/account-hash/image-id/public",
  "image_url": "https://imagedelivery.net/account-hash/image-id/public",
  "image_variants": {
    "thumbnail": "https://imagedelivery.net/account-hash/image-id/thumbnail",
    "medium": "https://imagedelivery.net/account-hash/image-id/medium", 
    "large": "https://imagedelivery.net/account-hash/image-id/large",
    "public": "https://imagedelivery.net/account-hash/image-id/public"
  },
  "caption": "Amazing steel coaster shot",
  "alt_text": "Steel Vengeance coaster with riders",
  "is_primary": false,
  "is_approved": false,
  "photo_type": "exterior",
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z",
  "date_taken": null,
  "uploaded_by_username": "photographer123",
  "file_size": 2048576,
  "dimensions": [1920, 1080],
  "ride_slug": "steel-vengeance",
  "ride_name": "Steel Vengeance",
  "park_slug": "cedar-point",
  "park_name": "Cedar Point"
}

Cloudflare Images Transformations

1. Built-in Variants

The integration provides these pre-configured variants:

  • thumbnail (150x150px): https://imagedelivery.net/account-hash/image-id/thumbnail
  • medium (500x500px): https://imagedelivery.net/account-hash/image-id/medium
  • large (1200x1200px): https://imagedelivery.net/account-hash/image-id/large
  • public (original): https://imagedelivery.net/account-hash/image-id/public

2. Custom Transformations

You can apply custom transformations by appending parameters to any variant URL:

Resize Examples:

# Resize to specific width (maintains aspect ratio)
https://imagedelivery.net/account-hash/image-id/public/w=800

# Resize to specific height (maintains aspect ratio)  
https://imagedelivery.net/account-hash/image-id/public/h=600

# Resize to exact dimensions (may crop)
https://imagedelivery.net/account-hash/image-id/public/w=800,h=600

# Resize with fit modes
https://imagedelivery.net/account-hash/image-id/public/w=800,h=600,fit=cover
https://imagedelivery.net/account-hash/image-id/public/w=800,h=600,fit=contain
https://imagedelivery.net/account-hash/image-id/public/w=800,h=600,fit=crop

Quality and Format:

# Adjust quality (1-100)
https://imagedelivery.net/account-hash/image-id/public/quality=85

# Convert format
https://imagedelivery.net/account-hash/image-id/public/format=webp
https://imagedelivery.net/account-hash/image-id/public/format=avif

# Auto format (serves best format for browser)
https://imagedelivery.net/account-hash/image-id/public/format=auto

Advanced Transformations:

# Blur effect
https://imagedelivery.net/account-hash/image-id/public/blur=5

# Sharpen
https://imagedelivery.net/account-hash/image-id/public/sharpen=2

# Brightness adjustment (-100 to 100)
https://imagedelivery.net/account-hash/image-id/public/brightness=20

# Contrast adjustment (-100 to 100)
https://imagedelivery.net/account-hash/image-id/public/contrast=15

# Gamma adjustment (0.1 to 2.0)
https://imagedelivery.net/account-hash/image-id/public/gamma=1.2

# Rotate (90, 180, 270 degrees)
https://imagedelivery.net/account-hash/image-id/public/rotate=90

Combining Transformations:

# Multiple transformations (comma-separated)
https://imagedelivery.net/account-hash/image-id/public/w=800,h=600,fit=cover,quality=85,format=webp

# Responsive image for mobile
https://imagedelivery.net/account-hash/image-id/public/w=400,quality=80,format=auto

# High-quality desktop version
https://imagedelivery.net/account-hash/image-id/public/w=1200,quality=90,format=auto

3. Creating Custom Variants

You can create custom variants in your Cloudflare Images dashboard for commonly used transformations:

  1. Go to Cloudflare Images dashboard
  2. Navigate to "Variants" section
  3. Create new variant with desired transformations
  4. Use in your models:
# In your model
class RidePhoto(TrackedModel):
    image = CloudflareImagesField(variant="hero_banner")  # Custom variant

4. Responsive Images Implementation

Use different variants for responsive design:

<!-- HTML with responsive variants -->
<picture>
  <source media="(max-width: 480px)" 
          srcset="https://imagedelivery.net/account-hash/image-id/thumbnail">
  <source media="(max-width: 768px)" 
          srcset="https://imagedelivery.net/account-hash/image-id/medium">
  <source media="(max-width: 1200px)" 
          srcset="https://imagedelivery.net/account-hash/image-id/large">
  <img src="https://imagedelivery.net/account-hash/image-id/public" 
       alt="Ride photo">
</picture>

/* CSS with responsive variants */
.ride-photo {
  background-image: url('https://imagedelivery.net/account-hash/image-id/thumbnail');
}

@media (min-width: 768px) {
  .ride-photo {
    background-image: url('https://imagedelivery.net/account-hash/image-id/medium');
  }
}

@media (min-width: 1200px) {
  .ride-photo {
    background-image: url('https://imagedelivery.net/account-hash/image-id/large');
  }
}

5. Performance Optimization

Best Practices:

  • Use format=auto to serve optimal format (WebP, AVIF) based on browser support
  • Set appropriate quality levels (80-85 for photos, 90+ for graphics)
  • Use fit=cover for consistent aspect ratios in galleries
  • Implement lazy loading with smaller variants as placeholders

Example Optimized URLs:

# Gallery thumbnail (fast loading)
https://imagedelivery.net/account-hash/image-id/thumbnail/quality=75,format=auto

# Modal preview (balanced quality/size)
https://imagedelivery.net/account-hash/image-id/medium/quality=85,format=auto

# Full-size view (high quality)
https://imagedelivery.net/account-hash/image-id/large/quality=90,format=auto

Testing and Verification

1. Verify Upload Functionality

# Test ride photo upload (requires existing ride with ID 1)
curl -X POST "http://localhost:8000/api/v1/rides/1/photos/" \
  -H "Authorization: Bearer your_test_token" \
  -F "image=@test_image.jpg" \
  -F "caption=Test upload"

# Test park photo upload (requires existing park with ID 1)
curl -X POST "http://localhost:8000/api/v1/parks/1/photos/" \
  -H "Authorization: Bearer your_test_token" \
  -F "image=@test_image.jpg" \
  -F "caption=Test park upload"

# Test with non-existent entity (should return 400 error)
curl -X POST "http://localhost:8000/api/v1/rides/99999/photos/" \
  -H "Authorization: Bearer your_test_token" \
  -F "image=@test_image.jpg" \
  -F "caption=Test upload"

2. Verify Image Variants

# Django shell verification
from apps.rides.models import RidePhoto

photo = RidePhoto.objects.first()
print(f"Image URL: {photo.image.url}")
print(f"Thumbnail: {photo.image.url.replace('/public', '/thumbnail')}")
print(f"Medium: {photo.image.url.replace('/public', '/medium')}")
print(f"Large: {photo.image.url.replace('/public', '/large')}")

3. Test Transformations

Visit these URLs in your browser to verify transformations work:

  • Original: https://imagedelivery.net/your-hash/image-id/public
  • Resized: https://imagedelivery.net/your-hash/image-id/public/w=400
  • WebP: https://imagedelivery.net/your-hash/image-id/public/format=webp

Future Enhancements

Potential future improvements:

  • Signed URLs for private images
  • Batch upload capabilities
  • Image analytics integration
  • Advanced AI-powered transformations
  • Custom watermarking
  • Automatic alt-text generation

Dependencies

  • django-cloudflare-images>=0.6.0 (already installed)
  • Proper environment variables configured
  • Cloudflare Images account setup
Reference in New Issue View Git Blame Copy Permalink