[ADP-753] OpenAPI: x-rate-limit

Guidelines

• For code generation purposes, you MAY add the x-rate-limit field to endpoints with rate limits in the OpenAPI documentation. NOTICE- it's not adding to the response body, but to the endpoint field! This is to help the code generator understand the rate limit information. If you don't have code generation mechanism, you MAY omit the x-rate-limit field in the OpenAPI documentation.

TIP

You SHOULD always add the RateLimit-* headers to the responses if you plan to rate limit the API!

openapi: 3.1.0
info:
  title: "Sample API"
  version: "1.0.0"
paths:
  /users:
    get:
      summary: "Fetch the user list"
      x-rate-limit:
        limit: 1000
        window: "PT1M"
      responses:
        '200':
          description: "Successful response"
          headers:
            headers:
              RateLimit-Limit:
                description: "The maximum number of requests allowed in the time window"
                schema:
                  type: integer
                  example: 1000
              RateLimit-Remaining:
                description: "The number of remaining requests in the current window"
                schema:
                  type: integer
                  example: 985
              RateLimit-Reset:
                description: "The time at which the current rate limit window resets"
                schema:
                  type: string
                  format: date-time
                  example: "2023-06-01T13:00:00Z"
        '429':
          description: "Rate limit exceeded"
          headers:
            Retry-After:
              description: "The number of seconds to wait before retrying"
              schema:
                type: integer
                example: 60
              RateLimit-Limit:
                description: "The maximum number of requests allowed in the time window"
                schema:
                  type: integer
                  example: 1000
              RateLimit-Remaining:
                description: "The number of remaining requests in the current window"
                schema:
                  type: integer
                  example: 985
              RateLimit-Reset:
                description: "The time at which the current rate limit window resets"
                schema:
                  type: string
                  format: date-time
                  example: "2023-06-01T13:00:00Z"

Related ADPs

• ADP-138: Rate Limiting
• ADP-43: API Rate Limiting

References

1. OpenAPI Specification
2. ISO 8601 Duration Format
3. IETF Draft: RateLimit Header Fields for HTTP

Changelog

• 2025-02-03: Add tips for x-rate-limit for code generation purpose and not to add to the response body.