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 {