Skip to content
Thryv AEP

Partial responses

Sometimes, a resource can be either large or expensive to compute, and the API needs to give the user control over which fields it sends back. Requesting fewer fields may also grant a performance boost.

Guidance

Section titled “Guidance”

APIs may support partial responses using field masks to grant users fine-grained control over which fields are returned.

If an API supports partial responses, it must use a query parameter named readMask.

  • The readMask parameter must be optional.
    • If readMask is omitted, it must default to return all fields, unless otherwise documented.
  • An API may support read masks on nested fields within arrays, but is not obligated to do so.
    • For example, given a book resource with an authors array, a read mask of title,authors.name would return only the book’s title and each author’s name (filtering out other author fields). If an API does not support this, it must treat array fields as all-or-nothing:
      • either the entire array with all nested fields is returned, or
      • the array is omitted entirely.
  • readMask must follow the guidelines in AEP-106 on query parameters.
parameters:
  - in: query
    name: readMask
    schema:
      type: string
    description: >-
      The fields to include in the response. If not provided, all fields are
      returned. Nested fields can be specified using dot notation. For example:
      `title,author.name`.

Error handling

Section titled “Error handling”

If a client specifies an invalid field name in the readMask parameter, the API must return a 400 Bad Request error response.

  • The error response should include a clear message indicating which field(s) are invalid. It should specify the exact field path that caused the error when possible (e.g., "Invalid field: 'author.middleName'" rather than just "Invalid field").
  • An API should not choose to ignore unrecognized fields and return the recognized subset instead of returning an error.
  • If the readMask syntax itself is malformed (e.g., invalid characters, improper nesting), the API must return a 400 Bad Request error with a message describing the syntax issue.

Changelog

Section titled “Changelog”
  • 2026-01-30: Change read_mask to readMask to match query param spec
  • 2025-12-23: Initial creation, adapted from Google AIP-157 and aep.dev AEP-157.