Course contentsShow
← System Design
Lesson 1786 of 1,91943. Real-World System: Rate Limiter ServiceFree lesson

API Contract: Request and Response Format

Designing the rate limiter API: sending user ID, resource, timestamp and returning allow/deny with headers.

API Contract: Request and Response Format

What You'll Learn

You'll learn how to design the rate limiter's API contract, including what information clients must send and what response structure they receive to determine if their request is allowed or denied.

The Core Idea

A rate limiter sits between clients and your backend services, deciding whether to allow or deny incoming requests. The API contract defines the structured conversation between the client and rate limiter.

Request Format

When a client makes a request, the rate limiter needs specific information to make an accurate decision:

Required fields:

  • user_id or client_id — identifies who is making the request
  • resource — what endpoint or action they're trying to access (e.g., /api/posts, send_message)
  • timestamp — when the request occurred (UTC milliseconds)

Think of it like showing your ID card (user_id), stating which room you want to enter (resource), and signing in with the current time (timestamp).

Response Format

The rate limiter returns a decision with helpful metadata:

{
  "allowed": true,
  "headers": {
    "X-RateLimit-Limit": 1000,
    "X-RateLimit-Remaining": 847,
    "X-RateLimit-Reset": 1678901234
  }
}

Response fields:

  • allowed — boolean decision (true/false)
  • Headers expose:
    • X-RateLimit-Limit: total requests allowed per window
    • X-RateLimit-Remaining: how many requests left
    • X-RateLimit-Reset: timestamp when the limit resets

These headers let clients implement smart retry logic and display rate limit information to users.

Why This Matters

A well-defined API contract ensures consistency, enables client-side optimization, and provides transparency about rate limit status without additional lookups.

Key Takeaway: The rate limiter API contract accepts user ID, resource, and timestamp in the request, then returns an allow/deny decision plus standard headers showing limit, remaining quota, and reset time.