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
2or4must declare aRateLimit-Limit,X-RateLimit-LimitorX-Rate-Limit-Limitheader, otherwise the rule reportsMissing rate limiting header; - a
429or503response must declare aRetry-Afterheader, otherwise the rule reportsMissing 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