Pagination limit parameter maximum constraint in OpenAPI 3.x

Question

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?

Zoha · Answer

Answer
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.
Why maximum is the recommended choice

It is part of the OpenAPI 3.x JSON Schema dialect (Draft 5 for 3.0, Draft 2019‑09 for 3.1).
All spec‑conforming tools – generators, linters, and gateway plugins – understand it.
It communicates the contract to API consumers and enables client‑side validation.

How to declare it
parameters:
  - 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.
Gateway‑level enforcement

Import the spec into the gateway. Most modern gateways (Kong, Apigee, AWS API Gateway, Envoy) offer request‑validation plugins that read maximum from the spec.
Enable the validation plugin. Example for Kong:
kong config set plugins.request_validator.enabled=true
kong reload

Verify the constraint. Send a request with limit=101 and confirm the gateway returns a 400/422 before the request reaches your service.
Optional hard‑cap. If the gateway can be bypassed or misconfigured, add a defensive check in the service layer that rejects values above the spec‑defined maximum.

Avoiding duplication
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.
What you might need to know
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.
Summary
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.

Pagination limit parameter maximum constraint in OpenAPI 3.x

1 answer

Answer

Why `maximum` is the recommended choice

How to declare it

Gateway‑level enforcement

Avoiding duplication

What you might need to know

Summary

Your perspective belongs here.

0 question comments