Search & Envelopes

Two finishing touches make collection endpoints pleasant to use: a search parameter for free-text queries, and a single envelope shape every collection shares.

Search vs structured filters

A ?q= parameter is for fuzzy, free-text search across a resource (“anything matching graphql”):

GET /articles?q=graphql

Structured filters (?status=published) answer precise questions; search answers vague ones. They compose — ?q=graphql&status=published searches within a filtered set. Keep them distinct: q is ranked, fuzzy, and may be backed by a search engine; filters are exact predicates.

A consistent envelope

Every collection response should share the same wrapper, so clients write the paging/handling code once:

JavaScript

function envelope(data, { page, limit, total, basePath }) {
  return {
    data,
    meta: { page, limit, total },
    links: {
      self: basePath + '?page=' + page,
      next: page * limit < total ? basePath + '?page=' + (page + 1) : null,
      prev: page > 1 ? basePath + '?page=' + (page - 1) : null,
    },
  };
}

const rows = [{ id: 1 }, { id: 2 }];
console.log(JSON.stringify(envelope(rows, { page: 1, limit: 2, total: 7, basePath: '/articles' }), null, 2));

The cost of total counts

Returning total is convenient but, on large tables, counting every matching row can be as expensive as the query itself. Options: cache the count, return an approximate count, or omit it entirely (cursor pagination often does — it offers next without a grand total).