operation-rate-limiting-defined

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

This rule checks that the responses of every operation declare the rate-limiting headers: RateLimit-Limit, X-RateLimit-Limit or X-Rate-Limit-Limit on every 2xx and 4xx response, and Retry-After on the 429 and 503 responses.

Rule details

A client that knows its quota and when to retry stays below the limit; one that does not learns about it from errors. Declaring the headers in the document tells client authors what to read and lets generated clients expose them.

The rule reports Missing rate limiting header and Missing Retry-After header on the response. It is a warning in the recommended, strict and all rulesets; turn it off when the API does not limit its clients.

Examples

Good. The quota on the success response, the delay on the 429 response.

paths:
  /users:
    get:
      responses:
        "200":
          description: A page of users.
          headers:
            RateLimit-Limit:
              description: Requests allowed per hour.
              schema:
                type: integer
        "429":
          description: Too many requests.
          headers:
            Retry-After:
              description: Seconds to wait before the next request.
              schema:
                type: integer

Bad. Nothing tells the client about the limit.

paths:
  /users:
    get:
      responses:
        "200":
          description: A page of users.

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.rules has the details.

commands:
  lint:
    rules:
      operation-rate-limiting-defined: off
Last updated on View as Markdown
Was this helpful?