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).

Advantages (Response Envelope)	Trade-offs
Metadata (pagination, total) travels in the same response	More verbose than a bare array
Consistent structure across every collection endpoint	Client has to unwrap `data` every time
Easy to add metadata later without a breaking change	A bare array is simpler for simple use cases
Search results carry `meta.total`, `meta.took` in the envelope

Common mistakes

Search that’s really just a filter Symptom:

GET /users?search=john queries every field with LIKE '%john%'
Slow on large tables and doesn’t rank by relevance
Real search should use a full-text search engine (Elasticsearch, PostgreSQL FTS)

Inconsistent envelopes Symptom:

GET /users returns { "data": [...], "meta": {...} }
GET /products returns { "items": [...], "pagination": {...} }
Define one standard envelope and use it on every collection endpoint

💡 Real-world examples

GitHub API:

Search: GET /search/repositories?q=rest+api+language:javascript&sort=stars

Envelope: { "total_count": 12345, "incomplete_results": false, "items": [...] }

Stripe API:

Consistent envelope: { "object": "list", "data": [...], "has_more": true, "url": "/charges" }

Every list endpoint uses the same shape

Sources: GitHub REST API — search, Stripe API — pagination