Linter rulesSwagger 2.0operation-rate-limiting-defined

operation-rate-limiting-defined

Since 0.9.0

This rule checks whether the responses of Swagger 2.0 operations declare rate limiting headers.

Rule Details

When an API limits the rate of requests, declaring the rate limiting headers lets consumers pace their requests and recover from throttling.

The operation-rate-limiting-defined rule checks the responses of every operation:

  • a response whose status code starts with 2 or 4 must declare a RateLimit-Limit, X-RateLimit-Limit or X-Rate-Limit-Limit header, otherwise the rule reports Missing rate limiting header;
  • a 429 or 503 response must declare a Retry-After header, otherwise the rule reports Missing Retry-After header.

A 429 response is therefore checked for both headers. Header names are compared case-sensitively. When a response is a $ref to a shared response under the root responses, the headers of the referenced response are used. The default response and other status codes are not checked.

Configuration

None.

Examples

Good. The success response declares a rate limit header, and the shared 429 response declares both Retry-After and a rate limit header.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      responses:
        '200':
          description: A list of pets.
          headers:
            X-RateLimit-Limit:
              description: The number of requests allowed per hour.
              type: integer
        '429':
          $ref: '#/responses/TooManyRequests'
responses:
  TooManyRequests:
    description: Too many requests.
    headers:
      Retry-After:
        description: The number of seconds to wait before retrying.
        type: integer
      RateLimit-Limit:
        description: The number of requests allowed per hour.
        type: integer

Bad. The 200 response has no rate limit header and the 503 response has no Retry-After header.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      responses:
        '200':
          description: A list of pets.
        '503':
          description: The service is unavailable.

When Not to Use It

You may disable this rule if your API does not impose any rate limits.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Further reading