Maximum Page Size Enforcement

Servers should enforce an upper bound on the number of records returned by a paginated API request. This prevents a client from requesting an excessively large response and helps keep memory, database, network, and latency costs bounded.

In a paginated API, clients commonly provide a parameter such as `pageSize` or `limit` to choose how many records they want. The server should not blindly honor arbitrarily large values because a single request could cause excessive database work or produce a very large response.

A server typically defines a maximum, such as 100 records per page. If the client requests a value above that limit, the API can either clamp it to the maximum or reject the request with a validation error. The chosen behavior should be documented and applied consistently.

The maximum should be enforced on the server rather than relying on clients to behave correctly. In Java backends, this validation can happen at the controller or service boundary before constructing the database query, ensuring that downstream components receive a safe value.

A page-size cap does not by itself solve every pagination problem. The API still needs a sensible pagination strategy, stable ordering, and appropriate database limits or query mechanisms. For very large datasets, cursor-based pagination can also help avoid some performance problems associated with large offsets.

Key points

• Always enforce a server-side upper bound for client-controlled page sizes.
• Choose a documented behavior for oversized requests: clamp or reject.
• Validate pagination parameters before executing the database query.
• A page-size cap protects database, memory, network, and latency resources.
• The cap is separate from the overall pagination strategy.

Interview questions

Is limiting page size enough to protect a paginated API from expensive queries?

No. It limits the number of records returned, but query cost can also depend on filtering, sorting, joins, indexes, and the pagination mechanism. Large offsets can become expensive on some database workloads even when the page size is small. Effective pagination therefore combines a page-size cap with appropriate query design and indexing.

Why should an API enforce a maximum page size?

The client controls the requested page size, so the server cannot assume that the value is small or reasonable. A very large request can increase database work, memory consumption, response size, and latency. Enforcing a maximum gives the server a predictable resource boundary.

What should happen when a client requests more than the maximum page size?

Two common choices are to clamp the requested value to the maximum or reject the request as invalid. Clamping is convenient for clients because the request can still succeed, while rejection makes the invalid input explicit. Whichever behavior is chosen should be documented and consistent.

Where would you enforce the page-size limit in a Java backend?

It should be enforced at a trusted server boundary, commonly in controller validation or a service-layer component responsible for pagination. The important point is that untrusted client input is normalized before it reaches database query construction. Centralizing the rule also helps keep behavior consistent across endpoints.

Would you clamp or reject a page-size request above the maximum?

I would choose based on the API contract and compatibility requirements rather than treating one behavior as universally correct. Clamping can make clients more resilient, while rejection gives immediate feedback that the requested input violates the contract. I would document the choice and return enough information for clients to understand the effective limit.