Enhancement Proposal: Rate Limiting Support in OpenAPI Specification

[stefvp]

Summary

This post proposes adding a standardized way to describe rate limiting policies in the OpenAPI Specification (OAS). Currently, rate limiting is widely implemented in API gateways and frameworks, but it is not formally represented in OAS, leading to fragmented and non-interoperable solutions.

---

Motivation & Use Cases

Rate limiting is a fundamental API protection and traffic management mechanism. However, it is typically configured outside of the API specification, resulting in a disconnect between API design and runtime behavior.

Key use cases:

• Client awareness
  API consumers cannot discover rate limits programmatically, leading to trial-and-error or reliance on external documentation.

• Tooling & automation
  Code generators, API gateways, and documentation tools cannot uniformly interpret rate limiting policies.

• Consistency across environments
  Different gateways (e.g., cloud providers, reverse proxies, frameworks) implement rate limiting differently, making portability difficult.

• Security & governance
  Rate limiting is part of API security posture but is not captured alongside authentication/authorization in OAS.

---

Proposed Solution

Introduce a standardized rate limiting definition using an x- vendor extension as a first step, with the goal of eventual standardization.

Example

paths:
  /api/resource:
    get:
      x-rateLimit:
        - algorithm: tokenBucket
          capacity: 10
          refillRate:
            tokens: 5
            interval: PT1S

paths:
  /pets:
    get:
      x-rateLimit:
        algorithm: slidingWindow
        key:
          in: ip
        requestCount: 15
        timeWindow: PT1M

paths:
  /pets:
    get:
      x-rateLimit:
        algorithm: slidingWindow
        key:
          in: header
          name: API-Key
        requestCount: 15
        timeWindow: PT1M

RateLimit Object Definition

A RateLimit object describes the algorithm, scope, and enforcement parameters of a rate limiting policy.
The object is introduced as the value of the x-rateLimit extension.

Field Name	Type	Applies To	Description
algorithm	string	Any	REQUIRED. The rate limiting algorithm to enforce. Valid values: fixedWindow, slidingWindow, tokenBucket.
description	string	Any	Explanation of the rate limiting policy and its intended usage.
key	Key Object	Any	Defines how requests are grouped for rate limit enforcement. If omitted, a single global counter is used. The key extracts a value from the request (e.g., client IP or request parameter).
requestCount	int32	fixedWindow, slidingWindow	REQUIRED. Maximum number of requests allowed within the specified timeWindow. Must be greater than 0.
timeWindow	string (ISO8601)	fixedWindow, slidingWindow	REQUIRED. Duration of the evaluation window (e.g., PT1M, PT1H).
capacity	int32	tokenBucket	REQUIRED. Maximum number of requests or tokens the bucket can hold.
refillRate	Rate Object	tokenBucket	REQUIRED. Defines how tokens are added back into the bucket over time.

---

Key Object Definition

The Key object defines how requests are grouped for rate limit enforcement.
It extracts a value from the incoming request and associates all requests with the same value to a shared rate limiting counter.

The design mirrors OpenAPI parameter identification (in and name) to allow policies to reference request elements already defined in the API specification.

Field Name	Type	Applies To	Description
in	string	Any	REQUIRED. Location from which the key value is extracted. Valid values: ip, header, query, path, cookie.
name	string	header, query, path, cookie	Name of the request field used as key (e.g., api-key, userId). Not required when in = ip.

---

Rate Object Definition

The Rate object defines a generic rate expression and is used by the token bucket algorithm.

Field Name	Type	Applies To	Description
tokens	int32	Any	REQUIRED. Number of requests (or tokens) processed per interval. Must be greater than 0.
interval	string (ISO8601)	Any	REQUIRED. Duration of the rate interval (e.g., PT1S, PT1M).

Justification

By introducing a standardized rate limiting model, OpenAPI can:

• Enable machine-readable API usage constraints
• Improve client-side adaptability (e.g., automatic backoff strategies)
• Support tooling and code generation (e.g., automatic enforcement in generated servers)
• Reduce vendor lock-in by abstracting gateway-specific configurations

This enhances both API design-time and runtime consistency.

---

Alternatives Considered

1. Status quo (no specification support)

Rate limiting remains external to OAS and implemented in gateways or middleware.

• No interoperability
• No tooling support
• No visibility for API consumers

2. Documentation-only approach

Describe rate limits in description fields.

• Not machine-readable
• Cannot be validated or enforced
• Prone to inconsistency

3. Runtime headers only (e.g., RateLimit-*)

Expose limits via HTTP response headers.

• Only visible after making requests
• Does not define policy at design time
• Insufficient for tooling and code generation

4. Gateway-specific extensions

Use provider-specific configurations (e.g., AWS, Azure).

• Tightly coupled to vendors
• Breaks portability
• Prevents standardization

---

Evidence / Early Implementation

This proposal has been prototyped using:

• x-rateLimit extensions embedded in OpenAPI documents
• Integration with server code generation (Flask-based implementations)
• Support for multiple algorithms (fixed window, sliding window, token bucket)

This demonstrates that:

• The model is machine-readable
• Policies can be enforced automatically
• The approach integrates cleanly with existing OpenAPI tooling

---

Open Questions

• What is the minimal common denominator across API gateways?
• How should advanced policies (e.g., per-user, per-API key, distributed limits) be represented?
• Should rate limiting be linked to security schemes or remain an independent component?

---

Next Steps

• Gather feedback from the community
• Refine the schema and field definitions
• Progress toward a formal proposal if sufficient support is established

Note: This proposal is part of ongoing academic research on formalizing rate limiting in OpenAPI, including prototype implementations and evaluation.

[lornajane]

Thanks for starting this conversation @stefvp , I have a few questions to try to understand the driver here. What led you to identify rate limiting as a specific feature? Is there prior art in this area that should be part of the context for this proposal?

[stefvp]

Hi @lornajane
Thanks for the questions!

Several factors led me to focus on rate limiting:

Security perspective:
Resource exhaustion is a well-known risk and is explicitly highlighted in the OWASP API Top 10 (e.g., “Unrestricted Resource Consumption. Rate limiting is one of the primary mitigations, yet it is not represented in OpenAPI.

API consumer perspective:
As a consumer, there is often very limited visibility into rate limiting policies. When information is available, it is typically buried in free-text descriptions or separate documentation, making it hard to use programmatically.

API developer / platform perspective:
From the implementation side, rate limiting is configured differently across API gateways and frameworks, with little consistency.
A standardized way to describe it in OpenAPI could:
-Help tooling detect missing or inconsistent policies
-Serve as a reminder to include rate limiting during design
-Improve portability by abstracting vendor-specific configurations

Regarding prior art:
There are related efforts such as standardized HTTP rate limit headers (e.g., RateLimit-*), but these focus on runtime communication, not design/specification. Most API gateways also support rate limiting, but each uses its own configuration syntax.

For example, the draft RFC on RateLimit headers
focuses on exposing quota state to clients. It defines limits primarily in terms of request counts and time windows (in seconds), with additional details conveyed via comments. It also introduces the concept of a partition key, with guidance that servers should document how it is derived.

This proposal builds on similar ideas but shifts the focus to design and machine readability.
It explicitly defines the algorithm used
Adds more flexible time window definitions (ISO 8601 instead of just seconds)
Adds a structured key definition based on request components (IP, headers, query, etc.)

This idea is to make rate limiting policies both explicit and processable by tooling, rather than implicit or descriptive.

[handrews]

@stefvp For anything involving HTTP headers, my concern is the same as for the sunset/deprecation discussion that is happening elsewhere:

We can already model HTTP response headers, so it's already possible to describe what RateLimit-* or other headers might say. If the concern is that they cannot be modeled with sufficient granularity because they are just treated as strings, that is valid, but better modeling for HTTP headers is planned for 3.3, so that should no longer be an issue.

Tools that understand HTTP headers will also know to look for them in Response Objects. Creating more structure in the OAS to re-state what headers can already state requires tools to look in multiple places (because some people might model the headers, and others might use the custom Object, and others might do both and contradict themselves). This does not seem to be an improvement to me.

It seems like there might be other things here beyond HTTP header use, and I'm not necessarily objecting to that. But I am skeptical of duplicating what we can already do with Response Objects and Header Objects (given that we are improving header modeling so it's not just a string you have to describe with a regexp, as that is obviously unsatisfactory for anything non-trivial).

[stefvp]

@handrews ,
Thanks for your feedback, I think there may be a bit of a misunderstanding about the intent of the proposal.

I’m not trying to model or duplicate HTTP headers like RateLimit-*. Those describe runtime state.

The goal of the x-rateLimit object is to explicitly model the rate limiting policy itself at design time i.e., what rules are applied (algorithm, key, limits), not what headers return after execution.
So rather than duplicating headers, this is about defining the policy that produces them, in a machine-readable way for tooling and validation.
I do agree that avoiding multiple sources of truth is important, so ideally headers would be a derived runtime representation of that policy.

A useful comparison is the Security Scheme Object: it describes authentication and is related to 401 Unauthorized, but does not model the header itself.
Similarly, the proposed RateLimit object describes the policy, not the 429 response, although they are clearly related.

Hope this clarifies things.

[miqui]

@handrews - I kinda share the same sentiment with @stefvp . However, this approach merits the current discussion similar the deprecation proposal.

[miqui]

@handrews > but better modeling for HTTP headers is planned for 3.3, so that should no longer be an issue.

Sorry, is there a discussion thread specifically on this or is it buried in another thread? Thanks.