Rules

Rules define specific rate limiting behavior for operations or HTTP endpoints within an application.

What is a Rule?

A rule specifies:

• What to rate limit: An operation name or HTTP path+method combination
• How fast to refill: Token refill rate (tokens per second)
• How much burst: Maximum tokens in the bucket

Rules provide fine-grained control over rate limiting, allowing you to set different limits for different operations or endpoints.

Rule Types

Operation-Based Rules

Rate limit by operation name - ideal for non-HTTP operations, background jobs, and internal services.

Examples:

• "sendEmail" - Rate limit email sending
• "processPayment" - Rate limit payment processing
• "generateReport" - Rate limit report generation
• "uploadFile" - Rate limit file uploads

Best for:

• Background jobs and workers
• Internal service-to-service calls
• Non-HTTP operations
• Business logic that doesn’t map to HTTP endpoints

Usage:

{
  "operation": "sendEmail",
  "refillRate": 5,
  "burstRate": 50
}

Path-Based Rules

Rate limit by HTTP path and method - ideal for REST APIs and web endpoints.

Examples:

• POST /api/users - Rate limit user creation
• GET /api/data - Rate limit data queries
• DELETE /api/items - Rate limit deletions
• PUT /api/profile - Rate limit profile updates

Best for:

• REST APIs
• Web endpoints
• HTTP services
• Public APIs

Usage:

{
  "path": "/api/users",
  "httpMethod": "POST",
  "refillRate": 10,
  "burstRate": 100
}

Rule Uniqueness

Within an application, rules must be unique:

• ✅ Each operation name can only have one rule
• ✅ Each path + method combination can only have one rule
• ✅ You can have both operation-based and path-based rules in the same application

Valid Configuration:

Application: API Service
Rules:
  ✅ operation: "sendEmail"
  ✅ operation: "processPayment"
  ✅ POST /api/users
  ✅ GET /api/users
  ✅ DELETE /api/users

Invalid Configuration:

Application: API Service
Rules:
  ❌ operation: "sendEmail" (refillRate: 5)
  ❌ operation: "sendEmail" (refillRate: 10) // Duplicate!
  
  ❌ POST /api/users (refillRate: 10)
  ❌ POST /api/users (refillRate: 20) // Duplicate!

Default Behavior

When a request doesn’t match any specific rule, LightRate automatically uses the application’s default token bucket.

This ensures that:

• No request is unprotected: Every operation gets rate limited
• Easy setup: Start with just an application, add specific rules as needed
• Graceful degradation: New endpoints are automatically protected

Example Flow

1. Request comes in for operation "sendNotification"
2. LightRate checks for a matching rule in the application
3. No specific rule found for "sendNotification"
4. Application’s default token bucket is used (e.g., 10 tokens/sec, burst of 100)

Choosing Rate Limits

Refill Rate

The refill rate determines sustained throughput:

• 1 token/sec = 1 request per second sustained = ~86K requests/day
• 10 tokens/sec = 10 requests per second sustained = ~864K requests/day
• 100 tokens/sec = 100 requests per second sustained = ~8.6M requests/day

Burst Rate

The burst rate handles traffic spikes:

• Burst of 10 = Can handle 10 instant requests
• Burst of 100 = Can handle 100 instant requests
• Burst of 1000 = Can handle 1000 instant requests

Common Patterns

Public API endpoint:

Refill Rate: 10 tokens/sec
Burst Rate: 100 tokens
Reasoning: Moderate sustained load, handle occasional bursts

Expensive operation (e.g., report generation):

Refill Rate: 1 token/sec
Burst Rate: 5 tokens
Reasoning: Limit sustained load, small burst allowance

Read-heavy endpoint:

Refill Rate: 100 tokens/sec
Burst Rate: 1000 tokens
Reasoning: High sustained throughput, large burst capacity

Write endpoint (e.g., database mutations):

Refill Rate: 5 tokens/sec
Burst Rate: 50 tokens
Reasoning: Conservative limits for expensive operations

Example Use Cases

Different Limits for Different Operations

Application: Email Service
Default: 10 tokens/sec, burst 100

Rules:
  sendEmail:          5 tokens/sec,  burst 50   (slower for individual emails)
  sendBulkEmail:      1 token/sec,   burst 10   (much slower for bulk)
  verifyEmail:        20 tokens/sec, burst 200  (faster for verifications)
  checkSpamScore:     50 tokens/sec, burst 500  (fastest for checks)

REST API with Different Endpoints

Application: Public REST API
Default: 50 tokens/sec, burst 500

Rules:
  POST /api/users:    10 tokens/sec, burst 100  (slower for creates)
  GET /api/users:     100 tokens/sec, burst 1000 (faster for reads)
  PUT /api/users:     10 tokens/sec, burst 100  (slower for updates)
  DELETE /api/users:  5 tokens/sec,  burst 50   (slowest for deletes)
  GET /api/search:    50 tokens/sec, burst 500  (moderate for search)

Tiered Access Levels

Application: Free Tier API
Default: 10 tokens/sec, burst 100
Rules:
  POST /api/data:     5 tokens/sec,  burst 50

Application: Pro Tier API
Default: 100 tokens/sec, burst 1000
Rules:
  POST /api/data:     50 tokens/sec, burst 500

Application: Enterprise Tier API
Default: 1000 tokens/sec, burst 10000
Rules:
  POST /api/data:     500 tokens/sec, burst 5000

Creating Rules

Rules are created through the LightRate dashboard or API with:

For Operation-Based Rules:

1. Name: Descriptive name (e.g., “Send Email”)
2. Operation: Operation identifier (e.g., “sendEmail”)
3. Refill Rate: Tokens per second
4. Burst Rate: Maximum tokens

For Path-Based Rules:

1. Name: Descriptive name (e.g., “Create User”)
2. Path: HTTP path (e.g., “/api/users”)
3. Method: HTTP method (e.g., “POST”)
4. Refill Rate: Tokens per second
5. Burst Rate: Maximum tokens

Best Practices

1. Start Conservative

Begin with lower limits and increase based on actual usage:

• Monitor your application’s behavior
• Analyze peak vs average load
• Adjust limits gradually

2. Use Descriptive Names

Choose clear names that explain what the rule does:

• ✅ “Send Bulk Email”, “Create User”, “Generate Report”
• ❌ “Rule 1”, “Fast Limit”, “Endpoint A”

3. Consider the Cost

Set stricter limits for expensive operations:

• Database writes → Lower limits
• External API calls → Lower limits
• Simple reads → Higher limits
• Cached responses → Higher limits

4. Monitor and Adjust

Regularly review your rate limits:

• Check rate limit hit rates
• Identify false positives (legitimate traffic blocked)
• Adjust limits based on business needs

5. Document Your Decisions

Keep track of:

• Why specific limits were chosen
• Expected usage patterns
• Business requirements driving the limits

Next Steps

• Token Bucket Algorithm - Understand how token buckets work
• Applications - Learn about organizing rules in applications
• Quick Start - Create your first rule