Skip to main content

​
Overview

The Photos API provides endpoints for uploading, managing, and retrieving photos associated with memorabilia items in your collection. Base URL: /api/photos/ Authentication: Token authentication required for all endpoints.

​
Interactive API Documentation

Full interactive API documentation for photo endpoints is available at /api/docs/ when running the FootyCollect server. The Swagger UI interface allows you to explore and test all endpoints with real-time responses.

​
OpenAPI Schema

The complete OpenAPI schema for photo endpoints is available at: 
GET /api/schema/
This provides a machine-readable specification of all photo endpoints, request/response schemas, and validation rules.

​
Photo Model

Photos are associated with items using Django’s GenericForeignKey pattern (see footycollect/collection/models.py:52-154):
​
id
integer
Unique identifier for the photo
​
content_type
integer
Content type ID for the associated object
​
object_id
integer
ID of the associated object (item)
​
image
file
The uploaded image file
​
image_avif
file
AVIF-optimized version of the image (auto-generated)
​
caption
string
Optional caption for the photo
​
order
integer
Display order of the photo (for sorting)
​
uploaded_at
datetime
When the photo was uploaded
​
user
integer
ID of the user who uploaded the photo

​
Features

​
Automatic Image Optimization

FootyCollect automatically creates AVIF versions of uploaded photos for better performance and smaller file sizes. This process is handled asynchronously using Celery tasks.

​
Thumbnail Generation

Thumbnails (100x100px) are automatically generated for all uploaded photos using ImageKit.

​
Photo Ordering

Photos can be reordered using the order field. The first photo (order=0) is typically used as the main photo for an item.

​
RESTful Conventions

Photo endpoints follow standard RESTful conventions:
  • GET /api/photos/ - List all photos
  • POST /api/photos/ - Upload a new photo
  • GET /api/photos/{id}/ - Retrieve a specific photo
  • PUT /api/photos/{id}/ - Full update of a photo
  • PATCH /api/photos/{id}/ - Partial update of a photo (e.g., caption, order)
  • DELETE /api/photos/{id}/ - Delete a photo

​
Sample Upload Request

curl -X POST "http://localhost:8000/api/photos/" \
  -H "Authorization: Token your_auth_token_here" \
  -F "image=@/path/to/photo.jpg" \
  -F "content_type=21" \
  -F "object_id=1" \
  -F "caption=Front view" \
  -F "order=0"

​
Sample Response

{
  "id": 42,
  "content_type": 21,
  "object_id": 1,
  "image": "http://localhost:8000/media/item_photos/photo_abc123.jpg",
  "image_avif": "http://localhost:8000/media/item_photos_avif/photo_abc123.avif",
  "caption": "Front view",
  "order": 0,
  "uploaded_at": "2024-01-15T14:30:00Z",
  "user": 5
}

​
File Storage

Photos are stored in the /media/item_photos/ directory, with AVIF versions in /media/item_photos_avif/. The application supports both local file storage and cloud storage (S3-compatible).

​
Cleanup

When a photo is deleted, both the original image and the AVIF version are automatically removed from storage to prevent orphaned files.

​
Learn More

OpenAPI Documentation

Access the full interactive API documentation with request/response examples and the ability to test endpoints directly.

OpenAPI Schema

Download the complete OpenAPI specification for integration with API clients and code generation tools.