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.

Operation

rpc GetBook ( GetBookRequest ) returns ( Book ) {
    option (google.api.http) = { get: "/{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".

Requests

message GetBookRequest {
  // The globally unique identifier for the resource
  string path = 10018 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "bookstore.example.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.

Responses

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

message Book {
  option (google.api.resource) = {
    type: "bookstore.example.com/book",
    pattern: [ "publishers/{publisher}/books/{book}" ],
    plural: "books",
    singular: "book"
  };


  // A Author.
  message Author {
    // Field for firstName.
    string firstName = 1;


    // Field for lastName.
    string lastName = 2;
  }


  // Field for author.
  repeated Author author = 5;


  // Field for isbn.
  repeated string isbn = 1 [(google.api.field_behavior) = REQUIRED];


  // Field for price.
  float price = 2 [(google.api.field_behavior) = REQUIRED];


  // Field for published.
  bool published = 3 [(google.api.field_behavior) = REQUIRED];


  // Field for edition.
  int32 edition = 4;


  // Field for path.
  string path = 10000;


  // Field for id.
  string id = 10001;
}

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

rpc GetBook ( GetBookRequest ) returns ( Book ) {
    option (google.api.http) = { get: "/{path=publishers/*/books/*}" };


    option (google.api.method_signature) = "path";
  }
message GetBookRequest {
  // The globally unique identifier for the resource
  string path = 10018 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "bookstore.example.com/book" }
  ];
}
message Book {
  option (google.api.resource) = {
    type: "bookstore.example.com/book",
    pattern: [ "publishers/{publisher}/books/{book}" ],
    plural: "books",
    singular: "book"
  };


  // A Author.
  message Author {
    // Field for firstName.
    string firstName = 1;


    // Field for lastName.
    string lastName = 2;
  }


  // Field for author.
  repeated Author author = 5;


  // Field for isbn.
  repeated string isbn = 1 [(google.api.field_behavior) = REQUIRED];


  // Field for price.
  float price = 2 [(google.api.field_behavior) = REQUIRED];


  // Field for published.
  bool published = 3 [(google.api.field_behavior) = REQUIRED];


  // Field for edition.
  int32 edition = 4;


  // Field for path.
  string path = 10000;


  // Field for id.
  string id = 10001;
}