Skip to content
mfbassoPublic

About

An open-source, lightweight API that fetches Creative Commons-licensed images from Flickr based on a keyword. Supports dynamic resizing, CDN caching, attribution headers, and modern image formats (JPG, WebP, AVIF). Perfect for quick integration into websites, bots, and applications.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Keyword Image Service

A Cloudflare Workers service that returns Creative Commons licensed images from Flickr based on keywords. Built for fast, deterministic image delivery with CDN caching and automated image processing.

🎯 Overview

This service provides a simple API to get CC-licensed images from Flickr based on keyword searches. Perfect for developers who need placeholder images, content illustration, or dynamic image content with proper attribution.

Key Features

  • Fast & Cached: CDN + KV + R2 caching for sub-200ms response times
  • Deterministic: Same keyword = same image (with optional seed control)
  • Scalable: Cloudflare Workers edge computing
  • Compliant: Only Creative Commons licensed images with automatic attribution
  • Flexible: Resize, format conversion, quality control
  • Rate Limited: 60 requests/minute per IP

πŸš€ Quick Start

Prerequisites

  1. Cloudflare account with Workers enabled
  2. Flickr API key
  3. Node.js 18+ and npm
  4. Wrangler CLI

Installation

# Clone the repository
git clone <repository-url>
cd keyword-image-service

# Install dependencies
npm install

# Login to Cloudflare
wrangler login

# Set up secrets
wrangler secret put FLICKR_API_KEY
# Enter your Flickr API key when prompted

Configuration

  1. Copy configuration template:
cp wrangler.toml.example wrangler.toml
  1. Update wrangler.toml with your KV and R2 resource IDs:
[[kv_namespaces]]
binding = "IMAGE_CACHE_KV"
id = "your-kv-namespace-id"

[[kv_namespaces]]
binding = "RATE_LIMIT_KV"
id = "your-rate-limit-kv-id"

[[r2_buckets]]
binding = "IMAGE_BUCKET"
bucket_name = "your-r2-bucket-name"
  1. Create KV namespaces:```bash wrangler kv:namespace create "IMAGE_CACHE_KV" wrangler kv:namespace create "RATE_LIMIT_KV"

3. **Create R2 bucket**:

```bash
wrangler r2 bucket create keyword-images

Development

# Start development server
npm run dev

# Deploy to staging
wrangler deploy --env staging

# Deploy to production
wrangler deploy

πŸ“š API Documentation

Image Endpoint

GET /image/:slug.jpg

Returns a processed JPEG image based on the keyword slug.

Parameters

Parameter Type Default Description
w number - Target width in pixels (max 3000)
h number - Target height in pixels (max 3000)
fit string cover Resize mode: cover or contain
q number 80 JPEG quality (60-90)
seed string - Deterministic seed for image selection
format string jpg Output format: jpg, webp, avif

Examples

# Basic image request
curl "https://your-worker.dev/image/mountain-landscape.jpg"

# Specific dimensions with cover fit
curl "https://your-worker.dev/image/sunset-beach.jpg?w=1200&h=800&fit=cover"

# High quality with seed for consistency
curl "https://your-worker.dev/image/urban-street.jpg?w=800&q=90&seed=abc123"

# WebP format via Accept header
curl -H "Accept: image/webp" "https://your-worker.dev/image/forest.jpg?w=600"

# Force specific format
curl "https://your-worker.dev/image/abstract-art.jpg?format=webp&w=400"

Response Headers

Content-Type: image/jpeg
Cache-Control: public, max-age=31536000, immutable
ETag: "a1b2c3d4-12345"
X-Attribution: "Sunset Beach β€” John Doe (CC BY 2.0)"
Link: <https://www.flickr.com/photos/johndoe/123456789>; rel="source"
X-RateLimit-Limit: 60
X-RateLimit-Window: 60

Metadata Endpoint

GET /image/:slug.json

Returns metadata about the selected image without processing the image data.

Response

{
  "title": "Beautiful Mountain Landscape",
  "author": "Jane Photographer",
  "license": "CC BY 2.0",
  "source_url": "https://www.flickr.com/photos/janephoto/987654321",
  "chosen_photo_id": "987654321",
  "width": 2048,
  "height": 1536,
  "attribution": "\"Beautiful Mountain Landscape\" β€” Jane Photographer (CC BY 2.0)"
}

HEAD Support

HEAD /image/:slug.jpg

Returns only headers (useful for checking image availability and getting metadata).

curl -I "https://your-worker.dev/image/nature-forest.jpg?w=800"

πŸ”§ Configuration

Environment Variables

Set these via wrangler secret put:

  • FLICKR_API_KEY - Your Flickr API key (required)

Wrangler Configuration

The wrangler.toml file configures:

  • KV namespaces for caching and rate limiting
  • R2 bucket for image storage
  • Environment-specific settings
  • Resource bindings

Rate Limiting

  • Limit: 60 requests per minute per IP
  • Window: Rolling 60-second window
  • Response: 429 with Retry-After header
  • Storage: Cloudflare KV with TTL

🎨 Image Processing

Supported Formats

  • JPEG: Default, widely supported
  • WebP: Modern format with better compression
  • AVIF: Next-gen format with best compression

Format Negotiation

  1. Query parameter format takes precedence
  2. Accept header used as fallback
  3. Defaults to JPEG if neither specified

Resize Modes

  • cover: Scale to fill target dimensions, crop if needed
  • contain: Scale to fit within target dimensions, preserve aspect ratio

Quality Control

  • Range: 60-90 (JPEG quality scale)
  • Default: 80 (good balance of quality/size)
  • Applied to all output formats

πŸ—„οΈ Caching Strategy

Multi-Layer Cache

  1. CDN: Cloudflare edge cache (31536000s TTL)
  2. KV: Metadata and photo mappings (24h TTL)
  3. R2: Original and processed images (permanent)

Cache Keys

  • Metadata: metadata:{slug}
  • Processed: processed/{slug}-{params-hash}.bin
  • Original: originals/{photo-id}.jpg

ETag Support

  • Generated from image content hash
  • Enables 304 Not Modified responses
  • Reduces bandwidth usage

πŸ” Image Selection

Source Criteria

  • Source: Flickr API only (MVP scope)
  • Licenses: Creative Commons (4,5,6,9,10)
  • Content: Photos only (not illustrations)
  • Safety: SafeSearch enabled

Selection Heuristics

  1. Size Preference: Images β‰₯ requested dimensions
  2. Orientation: Match target aspect ratio when possible
  3. Quality: Prefer higher resolution sources
  4. Availability: Fallback URL_O β†’ URL_K β†’ URL_H

Deterministic Selection

  • Without seed: First valid result (consistent for same query)
  • With seed: Hash-based stable selection from results
  • Cached: Once selected, choice is cached in KV

🚨 Error Handling

Error Responses

All errors return JSON with appropriate HTTP status:

{
  "error": "Description of the error",
  "suggestions": ["alternative", "keywords", "to", "try"]
}

Status Codes

  • 400: Invalid parameters (dimensions too large, etc.)
  • 404: No images found for keyword
  • 429: Rate limit exceeded
  • 500: Internal server error
  • 503: Service temporarily unavailable

Retry Logic

  • Flickr API: 2 retries with exponential backoff
  • Image download: 10s timeout with 1 retry
  • Graceful degradation on cache failures

πŸ“Š Monitoring

Structured Logging

All logs are JSON formatted with:

{
  "timestamp": "2024-08-15T10:30:00.000Z",
  "level": "info|warn|error",
  "message": "Human readable message",
  "data": {
    /* contextual data */
  }
}

Metrics

Stored in KV with 24h TTL:

  • metrics:cache_hits - Cache hit count
  • metrics:cache_misses - Cache miss count
  • metrics:images_processed - Images processed count

Access via KV dashboard or API.

πŸ”’ Security & Privacy

Image Content

  • SafeSearch enabled on all Flickr queries
  • Only Creative Commons licensed content
  • Metadata stripped from processed images

Rate Limiting

  • IP-based limiting (60/min)
  • Cloudflare IP detection (CF-Connecting-IP)
  • Graceful handling of proxy headers

CORS

  • Permissive CORS headers for frontend use
  • Access-Control-Allow-Origin: *
  • Standard preflight support

πŸ§ͺ Testing

Unit Tests

The project includes comprehensive unit tests for all core modules:

# Run tests once
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

Test Coverage

Current test coverage:

  • Utils: 83.92% - String manipulation, validation, content negotiation
  • Flickr Client: 68.12% - Photo selection, attribution, URL generation
  • Cache Manager: 74.35% - KV/R2 operations, ETag generation, metrics
  • Image Processor: 29.81% - Cache key generation, format negotiation

Test Structure

  • src/tests/utils.test.ts - Utility functions testing
  • src/tests/flickr-client.test.ts - Flickr API integration testing
  • src/tests/cache-manager.test.ts - Caching system testing
  • src/tests/image-processor.test.ts - Image processing utilities

Manual Testing

# Test basic functionality
curl "https://your-worker.dev/image/test.jpg"

# Test with parameters
curl "https://your-worker.dev/image/test.jpg?w=400&h=300&q=85"

# Test metadata
curl "https://your-worker.dev/image/test.json"

# Test rate limiting
for i in {1..65}; do curl "https://your-worker.dev/image/test$i.jpg"; done

Load Testing

Use tools like wrk or ab to test performance:

wrk -t12 -c400 -d30s "https://your-worker.dev/image/benchmark.jpg?w=800"

πŸš€ Deployment

Preview Deployment

wrangler deploy --dry-run  # Validate config
wrangler deploy --env staging

Production Deployment

wrangler deploy

Environment Management

  • Development: Local with wrangler dev
  • Staging: --env staging with preview resources
  • Production: Default environment with production resources

🀝 Contributing

Development Setup

  1. Fork the repository
  2. Create feature branch
  3. Install dependencies: npm install
  4. Start development: npm run dev
  5. Run tests: npm test
  6. Run tests with coverage: npm run test:coverage
  7. Lint code: npm run lint

Code Style

  • TypeScript strict mode
  • ESLint configuration provided
  • Prettier for formatting
  • Conventional commits preferred

πŸ“„ License

MIT License - see LICENSE file for details.

πŸ”— Resources

About

An open-source, lightweight API that fetches Creative Commons-licensed images from Flickr based on a keyword. Supports dynamic resizing, CDN caching, attribution headers, and modern image formats (JPG, WebP, AVIF). Perfect for quick integration into websites, bots, and applications.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages