Let clients ask for only the fields they need

How to do it

A mobile list that needs a name and a price should not download every description and image. Return all fields when fields is missing, so old clients keep working. Answer 400 for an unknown field name rather than ignoring it. Check access for each expanded record as for a direct read, as Authorise every object says. Expansion multiplies the work of one call, so count each expanded record against the page cap in Cap the page size. Keep the field list in the cache key from Set caching headers on every response.

Examples

JavaScript example

const PRODUCT_FIELDS = new Set(['id', 'name', 'price', 'description', 'images']);

export function pickFields(record, fieldsParam) {
  if (!fieldsParam) return record;
  const wanted = fieldsParam.split(',');
  const unknown = wanted.filter(field => !PRODUCT_FIELDS.has(field));
  if (unknown.length) throw new BadRequest(`unknown fields: ${unknown.join(', ')}`);
  return Object.fromEntries(wanted.map(field => [field, record[field]]));
}

Python example

PRODUCT_FIELDS = frozenset({"id", "name", "price", "description", "images"})

def pick_fields(record: dict, fields_param: str | None) -> dict:
    if not fields_param:
        return record
    wanted = fields_param.split(",")
    unknown = [field for field in wanted if field not in PRODUCT_FIELDS]
    if unknown:
        raise BadRequest(f"unknown fields: {', '.join(unknown)}")
    return {field: record[field] for field in wanted}

How to check

GET /products?fields=id,name returns objects with only those two fields. GET /products?fields=nope answers 400. GET /orders?expand=customer.company answers 400, since it asks for two levels.

Sources

• Google AIP-157 Partial responses

Related rules

• API-40 Authorise every object in API design
• API-22 Cap the page size in API design
• API-14 Set caching headers on every response in API design