Some HTTP APIs let a caller write something like `?expand[]=customer` so that a related object arrives inline instead of as a bare id. Explain what such an expansion parameter is for, and what constraints you would put on it when designing the API.

## Why expansion exists REST representations normally reference other resources by identifier or link rather than embedding them. That keeps each representation small, cacheable, and singly-owned. The cost falls on the client: rendering an order row that shows the customer's name means `GET /orders/42`, read `customer: "cus_123"`, then `GET /customers/cus_123`. For a list of fifty orders that is the classic N+1 round-trip problem, and on a high-latency link the round trips dominate everything else. An **expansion parameter** lets the caller opt into inlining. The canonical shape (popularised by Stripe) is a repeated bracketed parameter: `GET /v1/charges/ch_1?expand[]=customer&expand[]=invoice.subscription` Each value is a dot-path from the resource root. Where the unexpanded response had `"customer": "cus_123"`, the expanded one has `"customer": { "id": "cus_123", "object": "customer", ... }`. For list endpoints the path is usually rooted at the collection's item shape, e.g. `expand[]=data.customer`. ## Expansion versus field selection They are complementary and opposite in direction. Field selection *removes* attributes that are already part of the representation. Expansion *adds* the body of a resource that the representation only referenced. A mature API supports both, and they compose: project the parent down to three fields, expand one relation, project that too. ## The constraints that matter **Allow-list the expandable paths.** If expansion is implemented by generic graph traversal over your ORM, a caller can wander from `order → customer → account → all_orders` and turn one request into a database tour. Every expandable path should be an explicit, documented part of the contract; unknown paths return `400` naming the bad path. **Cap the depth.** Even inside an allow-list, `a.b.c.d` compounds. A hard limit (Stripe uses four levels) makes the worst case enumerable. **Refuse or bound to-many expansion.** Expanding a one-to-one relation adds one object. Expanding `order.items` when an order can have 10,000 items inlines an unpaginated collection into a response that has no pagination envelope for it. Either disallow to-many expansion, or return a capped, explicitly-truncated envelope (`{ data: [...], has_more: true }`) so the client can tell it did not get everything. **Authorize the expanded resource independently.** The most common security bug here is checking permission on the parent and then embedding the child unchecked. Expansion must be equivalent to the caller having issued the sub-`GET` themselves: same authorization, same field-level redaction. If the caller may not read the customer, the correct behaviour is to leave the id unexpanded (or fail the request) — never to leak the object because the parent was readable. **Make the polymorphism explicit.** A field that is a string when unexpanded and an object when expanded is awkward for statically-typed clients. Document it as a union, keep the `id` present inside the expanded object so code can read `typeof x === 'string' ? x : x.id`, and never change the *field name* based on expansion — that breaks every client that did not ask. **Budget the cost.** Each expansion is extra work: more joins, more service calls, more serialization. Count expansions toward rate limits or quota weights, apply a per-request timeout that accounts for fan-out, and consider disallowing deep expansion on high-traffic list endpoints entirely. **Caching.** An expanded response is a different representation with a different ETag and cache key, and its freshness is the *minimum* of the parent's and the embedded resources'. Embedding a fast-changing child into a long-cached parent quietly serves stale data. Either derive the cache lifetime from the shortest-lived component, or do not cache expanded responses. ## When not to offer it If the relation is nearly always needed, embed it unconditionally and stop making callers ask. If the relation is huge or highly dynamic, keep the reference and let clients fetch and cache it separately — a separately-cached child is often cheaper overall than repeatedly re-embedding it. Expansion earns its keep in the middle: relations that some callers need some of the time, where the round trip is the dominant cost.