Expandable resources

What it is for, and when to say no

A BookResponse carries an author id. A client that wants author names for a page of 20 books either makes 20 more requests or you invent /books?includeAuthors=true. Expansion is the general version of that: the client names what it wants, the server resolves it in one batched query, and the wire format says which it got.

Ask before building it. Expansion is a permanent contract and it is not free — every expandable field is a batcher to write, a query to index, and a payload that varies by request. Before adding it, ask:

• Which fields do clients actually follow? Usually one or two per resource. Making every reference expandable produces surface nobody uses.
• How many distinct resources does a page touch? One batch per expandable field per page is the design point. If a field's target is itself a large object, the payload grows fast.
• How deep? ?expand=author.books is supported and costs meaningfully more than ?expand=author — see the performance section, which is not a formality.
• Is a dedicated endpoint clearer? If a client always wants the expansion, an endpoint that returns the joined shape is simpler for everyone than an optional parameter that is never omitted.