Partial Responses (fields)

Why partial responses exist

Clients often need only a few fields. Returning full objects increases payload size, couples clients to fields they do not use, and slows down mobile experiences.

Fields parameter

A common approach: a fields query parameter listing desired fields.

GET /api/users?fields=id,name,createdAt

Nested fields

If you support nested fields, keep the syntax simple. Avoid designing a mini query language unless you truly need it.

Default fields vs expanded fields

• Return a small default representation.
• Allow opt-in expansions via fields or include.

Example: include pattern

GET /api/orders/987?include=items,customer

Security and privacy

Partial responses must not allow access to restricted fields. Always apply authorization rules before shaping the response.

Common mistakes

• Allowing clients to request hidden fields
• Inconsistent response shapes across endpoints
• Overcomplicated field syntax that becomes impossible to document

Checklist

• Default response is reasonable and not bloated.
• fields/include are allow-listed and documented.
• Authorization is applied before field selection.