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 in no ruleset: turn it on when the API limits 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