AIP-131

Standard methods: Get

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.

Resource-oriented design (AIP-121) honors this pattern through the Get method. These RPCs accept the URI representing that resource and return the resource.

Guidance

APIs should generally provide a get method for resources unless it is not valuable for users to do so. The purpose of the get method is to return data from a single resource.

Get methods are specified using the following pattern:

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

Request message

Get methods implement a common request message pattern:

message GetBookRequest {
  // The name of the book to retrieve.
  // Format: publishers/{publisher}/books/{book}
  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.

Errors

If the user does not have permission to access the resource, regardless of whether or not it exists, the service must error with PERMISSION_DENIED (HTTP 403). Permission must be checked prior to checking if the resource exists.

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

Changelog

• 2022-06-02: Changed suffix descriptions to eliminate superfluous "-".
• 2020-06-08: Added guidance on returning the full resource.
• 2019-10-18: Added guidance on annotations.
• 2019-08-12: Added guidance for error cases.
• 2019-08-01: Changed the examples from "shelves" to "publishers", to present a better example of resource ownership.
• 2019-05-29: Added an explicit prohibition on arbitrary fields in standard methods.