Features

This chapter covers the core features and capabilities of API Rate Controller.

Features

• Per-tenant limits — Different rate limits for each tenant based on their plan
• Sliding window — Accurate rate limiting using sliding window counters (not just fixed windows)
• Multiple windows — Enforce per-second, per-minute, per-hour, and per-day limits simultaneously
• Plan-based tiers — Define rate limit tiers (free, starter, pro, enterprise) with different limits
• Quota management — Monthly/daily quotas separate from burst rate limits
• Throttling — Gradual slowdown near limits instead of hard cutoff (optional)
• Overage handling — Allow overage with tracking, or hard-block at limit
• Rate limit headers — Standard X-RateLimit-* headers for every response
• IP-based fallback — Rate limit by IP when tenant is unknown (login, public endpoints)
• Analytics — Track limit hits, throttle events, and blocked requests per tenant
• Middleware pattern — Wrap any HTTP handler with rate limiting via decorator

Requirements

• Python 3.10+
• No external dependencies (stdlib only)

Quick Start

Follow this guide to get API Rate Controller up and running in your environment.

Quick Start

python src/main.py --init-demo

# Check rate limit status for a tenant
curl http://localhost:8009/api/limits/tenant_acme

# Simulate an API request (consumes 1 unit)
curl -X POST http://localhost:8009/api/check \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "tenant_acme", "endpoint": "/api/data", "cost": 1}'

# Get quota status
curl http://localhost:8009/api/quota/tenant_acme

# View rate limit analytics
curl http://localhost:8009/api/analytics/tenant_acme

# Manage plans
curl http://localhost:8009/api/plans

# Create a custom plan
curl -X POST http://localhost:8009/api/plans \
  -H "Content-Type: application/json" \
  -d '{"name": "custom", "requests_per_second": 50, "requests_per_minute": 2000, "requests_per_hour": 50000, "daily_quota": 500000}'

# Assign plan to tenant
curl -X PUT http://localhost:8009/api/tenants/tenant_acme/plan \
  -H "Content-Type: application/json" \
  -d '{"plan_id": "custom"}'

API Endpoints