Sparse Fieldsets, Expansion and Embedding — REST APIs in Depth

Over-fetching wastes bandwidth (especially on mobile); under-fetching causes chatty round trips. Two common REST techniques: sparse fieldsets (?fields=id,status,total) to return only selected fields, and expansion/embedding (?expand=customer,items.product) to inline related resources. Bound expansion depth, apply authorization to expanded resources, and include the options in cache keys. If many clients need very different shapes, that's a signal to consider a BFF or GraphQL.

Ways to shape responses

Criterion	Sparse fields + expand	BFF endpoint	GraphQL
Client flexibility	Medium	Low (per screen)	High
Server complexity	Low–medium	Low per endpoint	Higher (resolvers, limits)
HTTP caching	Good (URL-keyed)	Good	Harder (POST, persisted queries help)
Best for	Public REST APIs	First-party apps	Many diverse clients

GET /orders/ord_1?fields=id,status,total&expand=customer

{
  "id": "ord_1",
  "status": "paid",
  "total": {"amount": 2400, "currency": "EUR"},
  "customer": {"id": "cus_19", "name": "Ada Lovelace", "email": "[email protected]"}
}

Common pitfalls

Unbounded expansion depth (expensive queries, N+1).
Expanded objects bypassing authorization checks.
Caches ignoring the fields/expand params.

Key points

fields= to trim, expand= to inline
Bound depth; authorize expansions
Consider BFF/GraphQL when shapes diverge a lot

Further reading: Stripe: Expanding responses

Practice questions

What risk does expand introduce for authorization?

Answer

The expanded resource might belong to someone the caller can't access (e.g., another user's customer record); each expanded object needs the same access checks as a direct fetch.

How do sparse fieldsets help mobile clients?

Answer

They reduce payload size and parsing time on slow networks and low-power devices by returning only the fields a screen needs.