Skip to content
AEP
Blog

List

In REST APIs, it is customary to make a GET request to a resource collection’s URI (for example, /publishers/{publisher}/books) in order to retrieve a list of the resources within that collection.

Resource-oriented design (AEP-121) honors this pattern through the List method. These RPCs accept a parent collection (if one exists), and return a list of responses matching that input.

Guidance

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

When the GET method is used on a URI ending in a resource collection, the result must be a list of resources.

Operation

rpc ListBooks ( ListBooksRequest ) returns ( ListBooksResponse ) {
    option (google.api.http) = { get: "/{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’s message name.

  • The request message must match the RPC name, with a -Request suffix.

  • The response message must match the RPC name, with a -Response suffix.

    • The response should usually include fully-populated resources unless there is a reason to return a partial response (see AEP-157).

  • The HTTP verb must be GET.

  • If the collection has a parent resource, The URI should contain a field corresponding to the collection parent’s name.

    • This field should be called parent.
    • The URI should have a variable corresponding to this field.
    • The parent field should be the only variable in the URI path. All remaining parameters should map to URI query parameters.

  • There must not be a body key in the google.api.http annotation.

  • There should be exactly one google.api.method_signature annotation with a value of "parent" if a parent exists, and an empty string otherwise.

Requests

message ListBooksRequest {
  // A field for the parent of book
  string parent = 10013 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { }
  ];


  // The page token indicating the starting point of the page
  string page_token = 10010;


  // The maximum number of resources to return in a single page.
  int32 max_page_size = 10017;
}
  • A parent field must be included unless the resource being listed is a top-level resource. It should be called parent.
  • The max_page_size and page_token fields, which support pagination, must be specified on all list request messages. For more information, see AEP-158.

Note: The parent field in the request object corresponds to the parent variable in the google.api.http annotation on the RPC. This causes the parent field in the request to be populated based on the value in the URL when the REST/JSON interface is used.

Responses

List operations must return a page of results, with each individual result being a resource.

  • The array of resources must be named results and contain resources with no additional wrapping.
  • The string nextPageToken field must be included in the list response schema. 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 AEP-158.
  • The response struct may include a int32 totalSize (or int64 totalSize) 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 totalSize field should reflect the size of the collection after the filter is applied.
  • The response message must include a field corresponding to the resources being returned, named for the English plural term for the resource, and should not include any other repeated fields.
  • Fields providing metadata about the list request (such as string next_page_token or int32 total_size) must be included on the response (not as part of the resource itself).
message ListBooksRequest {
  // A field for the parent of book
  string parent = 10013 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { }
  ];


  // The page token indicating the starting point of the page
  string page_token = 10010;


  // The maximum number of resources to return in a single page.
  int32 max_page_size = 10017;
}

Errors

If the user does not have sufficient permission to know that the collection exists, the service should reply with an HTTP 404 error, regardless of whether or not the collection exists. Permission must be checked prior to checking whether the collection exists.

If the user does have proper permission, but the requested collection does not exist (generally because the parent does not exist), the service must reply with an HTTP 404 error.

Advanced operations

List methods may allow an extended set of functionality to allow a user to specify the resources that are returned in a response.

The following table summarizes the applicable AEPs, ordered by the precedence of the operation on the results.

OperationAEP
filterAEP-160
ordering (orderBy)AEP-132
pagination (nextPageToken)AEP-158
skipAEP-158

For example, if both the filter and skip fields are specified, then the filter would be applied first, then the resulting set would be the results that skip N entries of the filtered result.

Ordering

List methods may allow clients to specify sorting order; if they do, the request message should contain a string orderBy 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 - prefix; for example: "foo,-bar", "-foo,bar".
  • Redundant space characters in the syntax are insignificant. "foo, -bar", " foo , -bar ", and "foo,-bar" are all equivalent.
  • Subfields are specified with a . character, such as foo.bar or address.street.

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 showDeleted field in the list request that, if set, will cause soft-deleted resources to be included.

Interface Definitions

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


    option (google.api.method_signature) = "parent";
  }
message ListBooksRequest {
  // A field for the parent of book
  string parent = 10013 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { }
  ];


  // The page token indicating the starting point of the page
  string page_token = 10010;


  // The maximum number of resources to return in a single page.
  int32 max_page_size = 10017;
}
message ListBooksResponse {
  // A list of books
  repeated Book results = 10016;


  // The page token indicating the ending point of this response.
  string next_page_token = 10011;
}