Question
Pagination limit parameter maximum constraint in OpenAPI 3.x
Rin Finch
0 reputation · 16 Oct 2023, 10:30 UTC
26.9K views1
Loading…
0 reputation · 16 Oct 2023, 10:30 UTC
Goal: ensure that a pagination limit query parameter never exceeds a safe threshold that could cause memory exhaustion or excessive database load.
Constraint: the OpenAPI 3.x specification provides no native keyword to enforce a server‑side maximum on an integer query parameter; validation must be added by the implementation or API gateway.
Uncertainty: designers must decide whether to rely on the JSON Schema maximum property, a vendor extension such as x‑max‑limit, or external documentation, and how to guarantee that gateways and frameworks actually apply the bound.
What is the recommended way to express a maximum allowable value for a limit parameter within an OpenAPI 3.x document? Should teams use the schema maximum keyword or a custom extension like x‑max‑limit? How can API gateways be configured to enforce this constraint without duplicating logic in each service?
Use the standard JSON Schema maximum keyword in the parameter schema. Vendor extensions like x‑max‑limit are only hints and are not enforced by the spec itself, so they should not be relied on for cross‑tool enforcement.
swagger
openapimaximum is the recommended choiceparameters:
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 100
description: Number of items per page (max 100)
Replace 100 with the threshold that matches your safety requirements.
maximum from the spec.kong config set plugins.request_validator.enabled=true
kong reload
limit=101 and confirm the gateway returns a 400/422 before the request reaches your service.Keep the maximum value in a single place – the OpenAPI document. Use tooling that automatically generates the gateway config from that spec (e.g., Kong’s openapi plugin, Apigee’s ValidateOpenAPI policy). This eliminates drift between the contract and the enforcement logic.
If you are targeting a specific gateway, let us know which one. Some gateways require an extra plugin or a configuration flag to honor maximum on query parameters.
Declare the upper bound with maximum in the OpenAPI schema, enable a request‑validation plugin that reads that keyword, and optionally add a defensive check in the service to guard against misconfigurations. This approach keeps the spec as the single source of truth and works across the ecosystem.
Use comments to ask for clarification. Post a solution as an answer.
No question comments on this page.