AIP-132

Standard methods: List

In many APIs, it is customary to make a GET request to a collection's URI (for example, /v1/publishers/1/books) in order to retrieve a list of resources, each of which lives within that collection.

Resource-oriented design (AIP-121) honors this pattern through the List method. These RPCs accept the parent collection (and potentially some other parameters), and return a list of responses matching that input.

Guidance

APIs must provide a List method for resources unless the resource is a singleton. The purpose of the List method is to return data from a finite collection (generally singular unless the operation supports reading across collections).

List methods are specified using the following pattern:

rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books"
  };
  option (google.api.method_signature) = "parent";
}

• The RPC's name must begin with the word List. The remainder of the RPC name should be the plural form of the resource being listed.
• The request and response messages must match the RPC name, with Request and Response suffixes.
• The HTTP verb must be GET.
• The collection whose resources are being listed should map to the URI path.
  • The collection's parent resource should be called parent, and should be the only variable in the URI path. All remaining parameters should map to URI query parameters.
  • The collection identifier (books in the above example) must be a literal string.
• The body key in the google.api.http annotation must be omitted.
• If the resource being listed is not a top-level resource, there should be exactly one google.api.method_signature annotation, with a value of "parent". If the resource being listed is a top-level resource, there should be either no google.api.method_signature annotation, or exactly one google.api.method_signature annotation, with a value of "".

Request message

List methods implement a common request message pattern:

message ListBooksRequest {
  // The parent, which owns this collection of books.
  // Format: publishers/{publisher}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];

  // The maximum number of books to return. The service may return fewer than
  // this value.
  // If unspecified, at most 50 books will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 2;

  // A page token, received from a previous `ListBooks` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListBooks` must match
  // the call that provided the page token.
  string page_token = 3;
}

• A parent field must be included unless the resource being listed is a top-level resource. It should be called parent.
  • The field should be annotated as required.
  • The field must identify the resource type of the resource being listed.
• The page_size and page_token fields, which support pagination, must be specified on all list request messages. For more information, see AIP-158.
  • The comment above the page_size field should document the maximum allowed value, as well as the default value if the field is omitted (or set to 0). If preferred, the API may state that the server will use a sensible default. This default may change over time.
  • If a user provides a value greater than the maximum allowed value, the API should coerce the value to the maximum allowed.
  • If a user provides a negative or other invalid value, the API must send an INVALID_ARGUMENT error.
• The page_token field must be included on all list request messages.
• The request message may include fields for common design patterns relevant to list methods, such as string filter and string order_by.
• The request message must not contain any other required fields, and should not contain other optional fields except those described in this or another AIP.

Note: List methods should return the same results for any user that has permission to make a successful List request on the collection. Search methods are more relaxed on this.

Response message

List methods implement a common response message pattern:

message ListBooksResponse {
  // The books from the specified publisher.
  repeated Book books = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

• The response message must include one repeated field corresponding to the resources being returned, and should not include any other repeated fields unless described in another AIP (for example, AIP-217).
  • The response should usually include fully-populated resources unless there is a reason to return a partial response (see AIP-157).
• The next_page_token field, which supports pagination, must be included on all list response messages. It must be set if there are subsequent pages, and must not be set if the response represents the final page. For more information, see AIP-158.
• The message may include a int32 total_size (or int64 total_size) field with the number of items in the collection.
  • The value may be an estimate (the field should clearly document this if so).
  • If filtering is used, the total_size field should reflect the size of the collection after the filter is applied.

Ordering

List methods may allow clients to specify sorting order; if they do, the request message should contain a string order_by field.

• Values should be a comma separated list of fields. For example: "foo,bar".
• The default sorting order is ascending. To specify descending order for a field, users append a " desc" suffix; for example: "foo desc, bar".
• Redundant space characters in the syntax are insignificant. "foo, bar desc", " foo , bar desc ", and "foo,bar desc" are all equivalent.
• Subfields are specified with a . character, such as foo.bar or address.street.

Note: Only include ordering if there is an established need to do so. It is always possible to add ordering later, but removing it is a breaking change.

Filtering

List methods may allow clients to specify filters; if they do, the request message should contain a string filter field. Filtering is described in more detail in AIP-160.

Note: Only include filtering if there is an established need to do so. It is always possible to add filtering later, but removing it is a breaking change.

Soft-deleted resources

Some APIs need to "soft delete" resources, marking them as deleted or pending deletion (and optionally purging them later).

APIs that do this should not include deleted resources by default in list requests. APIs with soft deletion of a resource should include a bool show_deleted field in the list request that, if set, will cause soft-deleted resources to be included.

Errors

See errors, in particular when to use PERMISSION_DENIED and NOT_FOUND errors.

Further reading

• For details on pagination, see AIP-158.
• For listing across multiple parent collections, see AIP-159.

Changelog

• 2023-03-22: Fix guidance wording to mention AIP-159.
• 2023-03-17: Align with AIP-122 and make Get a must.
• 2022-11-04: Aggregated error guidance to AIP-193.
• 2022-06-02: Changed suffix descriptions to eliminate superfluous "-".
• 2020-09-02: Add link to the filtering AIP.
• 2020-08-14: Added error guidance for permission denied cases.
• 2020-06-08: Added guidance on returning the full resource.
• 2020-05-19: Removed requirement to document ordering behavior.
• 2020-04-15: Added guidance on List permissions.
• 2019-10-18: Added guidance on annotations.
• 2019-08-01: Changed the examples from "shelves" to "publishers", to present a better example of resource ownership.
• 2019-07-30: Added guidance about documenting the ordering behavior.
• 2019-05-29: Added an explicit prohibition on arbitrary fields in standard methods.