AIP-131

GET for individual resources

In REST APIs, it is customary to make a GET request to a resource's URI (for example, /v1/publishers/{publisher}/books/{book}) in order to retrieve that resource.

Our APIs honor this pattern by allowing GET requests to be sent to the resource URI, which returns the resource itself.

Guidance

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

Requests

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

GET /v1/publishers/{publisher}/books/{book} 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 request should not include optional fields in the query string unless described in another AIP.

Responses

Single-resource GET operations must return the resource itself, without any additional wrapping:

{
  "name": "publishers/lacroix/books/les-mis",
  "isbn": "978-037-540317-0",
  "title": "Les Misérables",
  "authors": ["Victor Hugo"],
  "rating": 9.6
}

Errors

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

If the user has sufficient permission to know that the resource exists, but is unable to access it, the service should reply with an HTTP 403 error.

If the user does have proper permission, but the requested resource does not exist, the service must reply with an HTTP 404 error.

Interface Definitions

Get operations are specified using the following pattern:

// Get a single book.
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{name=publishers/*/books/*}"
  };
  option (google.api.method_signature) = "name";
}
  • The RPC's name must begin with the word Get. The remainder of the RPC name should be the singular form of the resource's message name.
  • The request message must match the RPC name, with a -Request suffix.
  • The response message must be the resource itself. (There is no GetBookResponse.)
    • The response should usually include the fully-populated resource unless there is a reason to return a partial response (see AIP-157).
  • The HTTP verb must be GET.
  • The URI should contain a single variable field corresponding to the resource name.
    • This field should be called name.
    • The URI should have a variable corresponding to this field.
    • The name 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 "name".

Get operations also implement a common request message pattern:

// Request message to get a single book.
message GetBookRequest {
  // The name of the book to retrieve.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "library.googleapis.com/Book"
    }];
}
  • A resource name field must be included. It should be called name.
    • The field should be annotated as required.
    • The field should identify the resource type that it references.
  • The comment for the name field should document the resource pattern.
  • The request message must not contain any other required fields, and should not contain other optional fields except those described in another AIP.

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

Single-resource GET operations must be specified with consistent OpenAPI metadata:

paths:
  /publishers/{publisherId}/books/{bookId}:
    get:
      operationId: getBook
      description: Get a single book.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
  • The operationId must begin with the word get. The remainder of the operationId should be the singular form of the resource type's name.
  • The response content must be the resource itself. For example: #/components/schemas/Book
    • The response should usually include the fully-populated resource unless there is a reason to return a partial response (see AIP-157).
  • The URI should contain a variable for each individual ID in the resource hierarchy.
    • The path parameter for all resource IDs must be in the form {resourceName}Id (such as bookId), and path parameters representing the ID of parent resources must end with Id.