Filtering, sorting and paging links

Filtering, sorting and paging all shape which members of a collection come back, so they live in the query string of the collection's URI.

GET /orders?status=open&createdAfter=2026-01-01T00:00:00Z&sort=-createdAt,total&limit=50

Filters

The simplest convention is one parameter per field, with equality as the default: status=open. Ranges need a convention of their own, and two are common — named parameters (createdAfter, minTotal) or an operator in the name (total[gte]=100). Neither is a standard; choose one and use it everywhere. For several values, either repeat the parameter (status=open&status=paid) or use a comma list (status=open,paid) — again, one rule for the whole API.

The important decision is what happens to a parameter the endpoint does not know. Ignoring it looks forgiving, but a typo then changes the meaning of the request without any error:

1const orders = [2  { id: 1, status: "open" },3  { id: 2, status: "paid" },4  { id: 3, status: "open" },5  { id: 4, status: "cancelled" },6];7const FILTERS = ["status"];8 9function lenient(query) {10  return orders.filter((o) => FILTERS.every((f) => !(f in query) || o[f] === query[f])).map((o) => o.id);11}12 13function strict(query) {14  const unknown = Object.keys(query).filter((k) => !FILTERS.includes(k)).sort();15  if (unknown.length) return { status: 400, unknown };16  return { status: 200, ids: lenient(query) };17}18 19export function run() {20  const typo = { stauts: "open" };21  return {22    lenientCorrect: lenient({ status: "open" }),23    lenientTypo: lenient(typo),24    strictTypo: strict(typo),25  };26}

A client that misspelled status asked for open orders and received all of them — and a bulk action run on that result would touch everything. Rejecting unknown parameters with a 400 that names them turns a silent data bug into an obvious one.

Filtering on arbitrary fields is also an index question: every filter or sort you advertise is a query the database must answer quickly at full size, so the allowlist is a performance contract as much as an API one.

Sorting

A widespread convention is a sort parameter holding a comma-separated list of fields, each optionally prefixed with - for descending: sort=-createdAt,total. Three rules make it safe:

• Allowlist the fields. Never pass a client's string into an ORDER BY; map known names to known columns.
• Reject duplicates and unknowns instead of guessing.
• End with a unique field so the order is total. As the previous lesson showed, cursor pagination is wrong without it, and even offset pages can shuffle rows that tie.

Links to other pages

RFC 8288 defines the Link header: each link is a URI in angle brackets followed by parameters, most importantly rel, the relation type. The registered relations next, prev, first and last are exactly what paging needs, and a client can follow rel="next" without knowing how your cursors or offsets work.

1function linkHeader(base, links) {2  return Object.entries(links)3    .filter(([, query]) => query !== null)4    .map(([rel, query]) => `<${base}?${new URLSearchParams(query)}>; rel="${rel}"`)5    .join(", ");6}7 8export function run() {9  const base = "https://api.example.com/orders";10  return linkHeader(base, {11    first: { limit: "50" },12    next: { limit: "50", after: "WyIyMDI2IiwxMl0" },13    prev: null,14  });15}

Many APIs put the same links in the JSON body ("next": "...") as well, since some clients find headers awkward to read. Either is fine; a link the client can follow beats instructions it has to assemble.

Common mistakes

• Silently ignoring unknown query parameters, so a misspelled filter returns the whole collection.
• Interpolating the sort value into SQL — an injection hole and an unindexed query in one.
• Sorting without a unique final key, so rows with equal values swap places between requests.
• Different conventions on different endpoints (status=a,b here, status=a&status=b there).

What interviewers ask

• How would you design filtering and sorting for /orders? — query parameters on the collection, an allowlist of filterable and sortable fields, a documented range and multi-value convention, a unique tie-breaker in every sort.
• Should an API ignore unknown query parameters? — rejecting them is safer: a typo otherwise widens the result without warning.
• How does the client find the next page? — follow a link: a Link: <...>; rel="next" header (RFC 8288) or a next URL in the body.