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 should generally provide a List method for resources unless it is not valuable for users to do so. The purpose of the List method is to return data from a single, finite collection.

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 URL 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.
  • The method must document the default ordering, if one exists, or must explicitly document that the ordering behavior is unspecified.
  • There should be exactly one google.api.method_signature annotation, with a value of "parent".

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-example.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 should 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.

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.
  • 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.

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.

Further reading

  • For details on pagination, see AIP-158.

Changelog

  • 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.