Unbounded Collections: The Anti-Pattern With a Fuse

No one designs an unbounded endpoint on purpose. It happens by omission: GET /orders returns SELECT … FROM orders serialized, the table holds 200 rows, the response is 60KB in 20ms, and the code review approves — correctly, for that day. The contract, though, says something nobody meant: *the response scales with the table*. Every cost — query time, serialization CPU, response bytes, client parse memory — is now a linear function of business success. The endpoint has a fuse, and growth is the flame.

Follow the curve. At 10,000 rows: 3MB responses, 400ms — a slow endpoint on dashboards, below alert thresholds. At 100,000: 30MB, multiple seconds — mobile clients OOM parsing it, serverless consumers hit their timeout, and the JSON serializer's allocations trigger GC pauses that degrade *other* endpoints sharing the process. At 1,000,000: the endpoint is functionally down — but only for your biggest customers, because collection size tracks account size. That is the anti-pattern's cruelest property: it fails first and worst for exactly the users who matter most, while staging (200 rows, forever) stays green.

The failure also radiates below the API. One 30MB response occupies a connection-pool slot for seconds, streams through response buffers sized for kilobytes, and its query — a full scan, since there is nothing to bound — churns the database's buffer pool, evicting the hot pages every *other* endpoint depends on. Memory pressure from a handful of concurrent large responses is how an unbounded list on one endpoint becomes tail latency on all of them (see Payload Size: 20KB, 200KB, 5MB and API Performance: The Levers You Actually Own for the levers this bypasses).

The instinctive plan — "add pagination when it becomes a problem" — mistakes what kind of change pagination is. It is not an optimization; it is a semantic change to the response shape and the completeness promise. Clients bound to a bare array must now parse an envelope; clients that assumed one fetch equals the whole truth must grow a loop; sync jobs must learn cursors, partial progress and restart semantics. That is a breaking change multiplied by every consumer (see Backward Compatibility: The Real Rules) — deployed on the provider's emergency timeline, because the trigger was an incident, against consumers who each need their own release cycle to absorb it (see API Migration: Running the Change End to End).

Worse, the interim mitigations all lie to someone. Cap the response at 10,000 rows without an envelope, and the truncation is silent — the sync consumer processes 10,000 of 40,000 rows and reports success; you have converted an outage into data corruption, which is strictly worse because nothing pages. Add a limit parameter but default it to "all", and only new, informed clients are protected — the installed base keeps burning the fuse. The only clean exits are breaking ones, which is the whole argument for never entering: the bounded envelope costs three fields on day one and a migration program on day one thousand.

The same omission hides in shapes that do not look like list endpoints. Embedded collections — a customer response carrying orders: […] inline — are unbounded lists wearing a parent object (the fix: embed a bounded preview plus a link to the paginated collection, see Response Contracts Are Not Database Rows). Export jobs that buffer "the whole dataset" into one response or one file URL fail the same way at 10x the sizes (the fix: The Async Job Pattern with chunked or streamed results, see File Upload APIs: Authorize, Upload Directly, Confirm for the direct-to-storage pattern in reverse). And batch *writes* without item caps are the request-side twin (see Large Requests and Documented Limits and Partial Failure: When 3 of 5 Succeed).

The discipline generalizes past pagination into a review-time invariant: every response has a maximum size a human chose. Lists paginate with enforced max limits (Pagination: Choosing How Lists End); embedded collections are bounded previews with links; text fields have length caps; exports stream or chunk through jobs; and the numbers are written in the contract where consumers can plan against them. The question "what is the biggest response this can produce?" belongs on the endpoint-review checklist next to "what happens on retry?" — both are questions whose answers only get expensive when discovered in production (see Start With Requirements, Not Endpoints).

Enforcement must be server-side and unconditional, because the contract is only as bounded as its least-informed client. A documented-but-unenforced limit protects nobody: the oldest integration, written before the docs mentioned limits, is precisely the one still fetching everything. And when you *do* impose bounds on a previously unbounded endpoint, treat it as the breaking change it is — telemetry first to find who would be truncated, then per-consumer outreach with the paginated path, then enforcement with loud errors (400 limit_required), never silent truncation (see Consumer-Driven Evolution: Telemetry Before Breakage). Silent truncation is the one move worse than the original sin.