AIP-131

Standard methods: Get

In REST APIs, it is customary to make a GET request to a resource's URI (for example, /v1/invoices/:id) 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 GetInvoice(GetInvoiceRequest) returns (Invoice);
  • 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 GetInvoiceResponse.)
    • 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 id.
    • This field should be called id.
    • The URI should have a variable corresponding to this field.
    • The id 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 in the HTTP request.

Request message

Get methods implement a common request message pattern:

message GetInvoiceRequest {
  // The id of the invoice to retrieve.
  string id = 1 [(google.api.field_behavior) = REQUIRED)];
}
  • A resource id field must be included. It should be called id.
  • 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 id field in the request object corresponds to the id variable in the path parameter of the HTTP request. This causes the id field in the request to be populated based on the value in the URL when the REST/JSON proto handler is used.

Errors

See errors, in particular when to use PERMISSION_DENIED and NOT_FOUND errors.

Changelog

  • 2025-05-21: Forked from Google's AIP-131 with these changes:
    • Modified references of resource name to resource ID.