fastapi-traffic/examples/README.md

FastAPI Traffic Examples

This directory contains comprehensive examples demonstrating how to use the fastapi-traffic rate limiting library.

Basic Examples

01_quickstart.py

Minimal setup to get rate limiting working. Start here if you're new to the library.

• Basic backend and limiter setup
• Exception handler for rate limit errors
• Simple decorator usage

02_algorithms.py

Demonstrates all available rate limiting algorithms:

• Fixed Window - Simple, resets at fixed intervals
• Sliding Window - Most precise, stores timestamps
• Sliding Window Counter - Balance of precision and efficiency (default)
• Token Bucket - Allows controlled bursts
• Leaky Bucket - Smooths out traffic

03_backends.py

Shows different storage backends:

• MemoryBackend - Fast, ephemeral (default)
• SQLiteBackend - Persistent, single-instance
• RedisBackend - Distributed, multi-instance

04_key_extractors.py

Custom key extractors for different rate limiting strategies:

• Rate limit by IP address (default)
• Rate limit by API key
• Rate limit by user ID
• Rate limit by endpoint + IP
• Rate limit by tenant/organization
• Composite keys (user + action)

05_middleware.py

Middleware-based rate limiting for global protection:

• Basic middleware setup
• Custom configuration options
• Path and IP exemptions
• Alternative middleware classes

Advanced Examples

06_dependency_injection.py

Using FastAPI's dependency injection system:

• Basic rate limit dependency
• Tier-based rate limiting
• Combining multiple rate limits
• Conditional exemptions

07_redis_distributed.py

Redis backend for distributed deployments:

• Multi-instance rate limiting
• Shared counters across nodes
• Health checks and statistics
• Fallback to memory backend

08_tiered_api.py

Production-ready tiered API example:

• Free, Starter, Pro, Enterprise tiers
• Different limits per tier
• Feature gating based on tier
• API key validation

09_custom_responses.py

Customizing rate limit responses:

• Custom JSON error responses
• Logging/monitoring callbacks
• Different response formats (JSON, HTML, plain text)
• Rate limit headers

10_advanced_patterns.py

Real-world patterns and use cases:

• Cost-based limiting - Different operations cost different amounts
• Priority exemptions - Premium users exempt from limits
• Resource-based limiting - Limit by resource ID + user
• Login protection - Brute force prevention
• Webhook limiting - Protect external services
• Request fingerprinting - Spam prevention
• Time-of-day limits - Peak vs off-peak hours
• Cascading limits - Per-second, per-minute, per-hour

Running Examples

Each example is a standalone FastAPI application. Run with:

# Using uvicorn directly
uvicorn examples.01_quickstart:app --reload

# Or run the file directly
python examples/01_quickstart.py

Testing Rate Limits

Use curl or httpie to test:

# Basic request
curl http://localhost:8000/api/basic

# With API key
curl -H "X-API-Key: my-key" http://localhost:8000/api/by-api-key

# Check rate limit headers
curl -i http://localhost:8000/api/data

# Rapid requests to trigger rate limit
for i in {1..20}; do curl http://localhost:8000/api/basic; done

Environment Variables

Some examples support configuration via environment variables:

• RATE_LIMIT_BACKEND - Backend type (memory, sqlite, redis)
• REDIS_URL - Redis connection URL for distributed examples

Requirements

Basic examples only need fastapi-traffic and uvicorn:

pip install fastapi-traffic uvicorn

For Redis examples:

pip install redis