Gateway RidgeISSUE #29 of 35

api design · pagination · filtering · expansion

Gateway GusVSTimeout Titan

Gateway Gus saysBake pagination, filtering, and expansion into list endpoints from day one.

Any endpoint returning a collection needs limits. Ship pagination (default + max page size), filtering/sorting via query params, and optionally field selection and expansion (?expand=author to inline related data and save round-trips). Designing these in from the start avoids painful breaking changes when the dataset grows.

Power-ups you unlock

Always paginate collections (default + max)
Filter/sort via consistent query params
Field selection trims payloads
Expansion inlines related data, saves round-trips

Timeout Titan attacks — common mistakes

Unbounded list endpoints
Adding pagination later as a breaking change
No consistent filter/sort grammar

Boss battleDesign a list endpoint with pagination, a filter, and an expand option.

Example code

<!doctype html><html><head><meta charset="utf-8"></head>
<body style="background:#06040d;color:#e6e0ff;font-family:monospace;padding:20px"><pre>GET /posts?status=published&amp;sort=-date
        &amp;limit=20&amp;after=p_88&amp;expand=author</pre></body></html>

▶ Open the interactive comic issue

‹ Api Design · Resources First · Then Verbs Api Design · The Principle Of Least Surprise ›