10. Hosted deployment and review

The danger: If your database is compromised (leaked backup, SQL injection, stolen credentials), attackers immediately have working API keys. They can impersonate legitimate users, consume quotas, exfiltrate data, and cover tracks by using real user credentials.

Attack hashing prevents: Database leaks become useless. Attackers see hashes like a3f5b..., not keys like xQz4K8m_NpD1.... They can't use hashes for API requests. Computing the original key from a SHA-256 hash is computationally infeasible; it would take millions of years with current technology.

The pattern: treat API keys like passwords. Hash with SHA-256 (or bcrypt for slower verification, which makes brute-forcing leaked hashes slower too). Store only the hash. Show the raw key once at generation and never again. Stripe, GitHub, and AWS all work this way; if a user loses the key, they rotate to a new one rather than recovering the old one.

What's happening: Fixed-window rate limiting resets at hourly boundaries (15:00, 16:00, 17:00), not relative to first request. When they hit 100 requests at 15:43, they're rate-limited until 16:00, the next hour boundary. Waiting 5 minutes (until 15:48) doesn't help because they're still in the 15:00-16:00 window.

Why this design: Fixed windows are simple to implement and reason about. "Your quota is 100 requests per hour starting each hour at :00" is clear. Calculating resets is trivial (truncate to hour boundary, add 1 hour). No complex sliding window math.

The fix from the server side: the 429 should include both the reset boundary and the seconds-until-reset, e.g. {"detail": "Rate limit exceeded. Resets at 16:00 (in 720 seconds)", "reset_at": "2026-05-25T16:00:00+00:00"}. A confused user reads "Resets at 16:00"; a confused script parses reset_at.

The problem: Sequential IDs are predictable. If I get key "1234", I can guess "1235" and "1236" exist. Automated scanning tries all possible values. With sequential IDs, there are only N keys to try (where N is total users). An attacker can enumerate all valid keys systematically.

What makes good API keys: Cryptographically secure randomness (256 bits minimum), no patterns or predictability, URL-safe characters only. Using secrets.token_urlsafe(32) generates 43-character strings with 2^256 possible values; enumeration is computationally infeasible.

Attack scenario with sequential keys: Attacker registers, gets key "5000". Script tries 4999, 5001, 5002... Each try has high success probability. Script finds 100 valid keys in minutes. Attacker can impersonate any user.

With random keys: Each key is 43 random characters. Trying random strings has 1 in 2^256 chance of success. Would take billions of years to guess one valid key.

The problem: Each request needs a database connection. With 5 connections in the pool and 10 concurrent requests, 5 requests get connections and 5 wait. If those 5 requests are slow (1+ seconds), the waiting requests time out.

Pool sizing formula (Little's Law): pool_size ≥ arrival_rate × average_request_duration. If you handle 20 requests/second and each request takes 100ms, you need ~2 concurrent connections (20 × 0.1). If requests take 1 second instead, you need ~20 (20 × 1). The pool sizes the steady-state in-flight work, not the per-second throughput.

Multi-service consideration: If you run 4 API servers, each with pool_size=10 and max_overflow=5, the worst-case footprint is 4 × (10 + 5) = 60 connections. That total must stay below the database's max_connections. Formula: servers × (pool_size + max_overflow) ≤ database_max_connections.

Hosted PostgreSQL plans: managed databases usually have lower connection limits than your local PostgreSQL install. The chapter's database.py uses pool_size=5, max_overflow=10, which bursts to 15 under load and leaves headroom for database tools and migrations on a small single-worker deploy.

Production approach: Monitor connection usage. If pool is frequently exhausted, either increase pool_size or optimize queries to release connections faster. Long-running queries should not hold connections, use async processing instead.

The problem: Fixed TTL caching doesn't adapt to importance. Breaking news deserves immediate updates. Regular articles can stay cached longer.

Solution 1: Category-based TTL

# Shorter cache for urgent categories
CACHE_DURATIONS = {
    "breaking": 5,      # 5 minutes
    "politics": 15,     # 15 minutes
    "technology": 60,   # 1 hour
    "entertainment": 120 # 2 hours
}

def get_cache_duration(category: str) -> int:
    return CACHE_DURATIONS.get(category, 60)

Solution 2: Manual invalidation endpoint Admin endpoint to purge cache for specific categories or sources. When breaking news hits, admin calls POST /admin/cache/invalidate?category=politics to force refresh.

Solution 3: Smart refresh triggers Monitor external APIs for article count changes. If NewsAPI suddenly has 50 new articles in "politics" category (normally 5-10), invalidate cache and refetch immediately.

Trade-offs: More complex caching logic increases maintenance burden. Balance freshness requirements with implementation complexity. For most APIs, category-based TTL provides good balance.

Problems aggregation solves:

• Response normalisation: NewsAPI uses publishedAt, Guardian uses webPublicationDate. Clients would need format-specific parsing for each source. Aggregator provides one consistent format.
• Authentication complexity: Each API has different auth methods. NewsAPI uses query parameter keys, Guardian uses different parameter names. Aggregator presents one authentication scheme.
• Rate limit management: Clients hitting both APIs directly consume quotas twice as fast. Aggregator caches intelligently, reducing external API calls by 80-90%.
• Failure handling: If NewsAPI is down, clients must implement fallback logic. Aggregator handles this transparently, trying alternate sources automatically.
• Cost optimization: Multiple clients calling external APIs directly multiplies API costs. One aggregator serving many clients reduces external API usage dramatically.

Real-world example: This is how Stripe aggregates payment processors, how travel sites aggregate airlines, how Google News aggregates thousands of publishers. Aggregation provides value through simplification, reliability, and cost reduction.

Problems without mocking:

• Tests become slow: Network calls take 200-500ms each. Test suite with 50 API calls takes 10-25 seconds instead of under 1 second. Slow tests don't get run frequently.
• Tests become flaky: External APIs have downtime, rate limiting, and network failures. Tests fail randomly when APIs are unavailable, even though your code is correct.
• Tests consume quota: Running tests 20 times per day against real APIs burns through free tier limits. You hit rate limits and can't run tests.
• Can't test error handling: How do you test your "external API is down" error handling if you're calling the real API that's currently up? Mocks let you simulate failures.
• Tests lack isolation: External API changes break your tests even though your code didn't change. Tests should only fail when YOUR code is broken.

With mocks: the suite runs in under a second, doesn't fail on network blips, doesn't consume external quotas, and can exercise every error path on demand. Tests only break when your code breaks.