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 must provide a get method for resources. 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.
- This field should be called
- There must not be a
body
key in thegoogle.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 must 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
See errors, in particular when to use PERMISSION_DENIED and NOT_FOUND errors.
Changelog
- 2023-03-17: Align with AIP-122 and make Get a must.
- 2022-11-04: Aggregated error guidance to AIP-193.
- 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.