Back to docsRecipe

Partial-response (fields/sparse) pattern

Let API consumers request only the fields they need. Reduces payload size, speeds up mobile clients, and keeps your responses lean.

How it works

Clients pass a ?fields= query parameter with a comma-separated list of property paths. The server strips every key not in that whitelist before serializing the response.

Request

GET /api/users/42?fields=id,email,profile.name

Response (200)

{
  "id": 42,
  "email": "ada@meridian.dev",
  "profile": {
    "name": "Ada"
  }
}

Implementation sketch

  1. Parse fields into a Set<string>.
  2. Walk the response object recursively. Drop any key whose dot-joined path is absent from the set.
  3. If fields is missing or empty, return the full resource (backward-compatible).
  4. Return 400 Bad Request when an unknown field is requested.

When to use

  • Mobile or low-bandwidth clients that need tiny payloads.
  • List endpoints where each item carries dozens of fields.
  • Public APIs where you want to minimize over-fetching.

Tip: Combine with cursor pagination for ultra-lean list responses.