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_idorclient_id— identifies who is making the requestresource— 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 windowX-RateLimit-Remaining: how many requests leftX-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.