AIP-132

GET for collections

In REST APIs, it is customary to make a GET request to a resource collection's URI (for example, /v1/publishers/{publisher}/books) in order to retrieve a list of the resources within that collection. These are sometimes colloquially called "list" operations.

Guidance

APIs should generally provide a GET method for resource collections unless it is not valuable for users to do so. When the GET method is used on a URI ending in a resource collection, the result should be a list of resources. For more information about using the GET method on a URI ending with a discrete resource ID, see AIP-131.

Requests

Collection GET operations must be made by sending a GET request to the resource collection's URI:

GET /v1/publishers/{publisher}/books HTTP/2
Host: library.googleapis.com
Accept: application/json

• The HTTP method must be GET.
  • The request must be safe and must not have side effects.
• There must not be a request body.
  • If a GET request contains a body, the body must be ignored, and must not cause an error.
• The request must not require any fields in the query string.
  • The query string may include fields for common design patterns relevant to list methods, such as string filter and string orderBy.
  • The query string may include custom fields if necessary for a specific resource, but not in place of any of the common fields for list methods.

Responses

Collection GET operations must return a page of results, with each individual result being a resource:

{
  "results": [
    {
      "name": "publishers/lacroix/books/les-mis",
      "isbn": "978-037-540317-0",
      "title": "Les Misérables",
      "authors": ["Victor Hugo"],
      "rating": 9.6
    },
    {
      "name": "publishers/lacroix/books/hunchback-of-notre-dame",
      "isbn": "978-140-274575-1",
      "title": "The Hunchback of Notre Dame",
      "authors": ["Victor Hugo"],
      "rating": 9.3
    }
  ],
  "nextPageToken": "xyz"
}

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

Note: List methods may return the complete collection to any user with permission to make a successful List request on the collection, or may return a collection only containing resources for which the user has read permission. This behavior should be clearly documented either for each List method or as a standard convention in service-level documentation. Permission checks on individual resources may have a negative performance impact so should be used only where absolutely necessary.

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.

Note: An empty collection which the user has permission to access must return 200 OK with an empty results array, and not 404 Not Found.

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.

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

Interface Definitions

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

// Request message to list a collection of books.
message ListBooksRequest {
  // The publisher to list books for.
  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 send fewer.
  int32 max_page_size = 2;

  // The page token.
  // If a `next_page_token` value was received on a previous
  // ListBooks call, providing it here will return the next page.
  string page_token = 3;
}

// Response message for listing a collection of books.
message ListBooksResponse {
  // The books under the umbrella of the given publisher.
  repeated Book results = 1;

  // The token to retrieve the next page. This is populated if and only if
  // there are more pages.
  string next_page_token = 2;
}

paths:
  /publishers/{publisherId}/books:
    parameters:
      - name: publisherId
        in: path
        description: The publisher to list books for.
        required: true
        schema:
          type: string
    get:
      operationId: listBooks
      description: Get a collection of books.
      parameters:
        - name: pageToken
          in: query
          description: |
            The page token.
            If a `next_page_token` value was received on a previous
            ListBooks call, providing it here will return the next page.
          schema:
            type: string
        - name: maxPageSize
          in: query
          description: |
            The maximum number of books to return.
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBooksResponse'