operation-rate-limiting-defined

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at warning, All at error

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.

The OpenAPI linter has a rule of the same name, operation-rate-limiting-defined, for OpenAPI 3.x documents.

Turn the rule off if your API does not impose any rate limits.

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.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        operation-rate-limiting-defined: off

Further reading

Was this helpful?