Skip to content
AEP

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 (AEP-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.
  • Some resources take longer to be retrieved than is reasonable for a regular API request. In this situation, the API should use a long-running operation.

Requests

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.example.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 AEP.

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
}

The response should usually include the fully-populated resource unless there is a reason to return a partial response (see AEP-157).

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:

rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
      get: "/v1/{path=publishers/*/books/*}"
    };
    option (google.api.method_signature) = "path";
  }
  • 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 HTTP verb must be GET.
  • The URI should contain a single variable field corresponding to the resource path.
    • This field should be called path.
    • The URI should have a variable corresponding to this field.
    • The path 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 "path".

Get operations also implement a common request message pattern:

message GetBookRequest {
  // The path of the book to retrieve.
  string path = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "library.googleapis.com/Book"
    }];
}
  • A resource path field must be included. It should be called path.
    • The field should be annotated as REQUIRED.
    • The field should identify the resource type that it references.
  • The comment for the path 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 AEP.

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