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. 在 REST API 中，习惯上向资源的 URI（例如，/v1/publishers/{publisher}/books/{book}）发出GET请求以检索该资源。

Resource-oriented design (AIP-121) honors this pattern through the Get method. These RPCs accept the URI representing that resource and return the resource. 面向资源的设计 (AIP-121) 通过 Get 方法致敬这种模式。 这些 RPC 接受代表该资源的 URI 并返回该资源。

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. APIs 应该为资源提供一个get方法除非它不是对用户这样做很有价值。get方法的目的是返回一个单独资源。

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.

  • RPC的名字必须以Get单词开始。RPC 名称的其余部分应该是资源消息名称的单数形式。

  • The request message must match the RPC name, with a -Request suffix.

  • 请求的message 必须匹配 RPC 名称，并带有 -Request 后缀。(例如: BookResquest)

  • The response message must be the resource itself. (There is no GetBookResponse.)

  • 响应消息必须是资源本身。 （没有GetBookResponse。）
    • The response should usually include the fully-populated resource unless there is a reason to return a partial response (see AIP-157).
    • 响应应该通常包括完整的资源，除非有理由返回部分响应(see AIP-157).
  • The HTTP verb must be GET.
  • HTTP 动词必须是 GET。
  • The URI should contain a single variable field corresponding to the resource name. URI 应该包含与资源名称对应的单个变量字段。
    • This field should be called name. 这个字段应该叫作name。
    • The URI should have a variable corresponding to this field.　
    • 这个URI 应该　有一个和这个字段对应的变量。
    • The name field should be the only variable in the URI path. All remaining parameters should map to URI query parameters.
    • name 字段应该是 URI 路径中的唯一变量。 所有剩余的参数应该映射到 URI 查询参数。
  • There must not be a body key in the google.api.http annotation.
  • google.api.http 注释中不能有 body 键。
  • There should be exactly one google.api.method_signature annotation, with a value of "name".
  • 应该只有一个 google.api.method_signature 注释，其值为 "name"。

Request message

Get methods implement a common request message pattern: Get 方法实现了一个常见的请求消息模式：

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.
  • 必须包含资源名称字段。 它应该被称为name。
  • The comment for the name field should document the resource pattern.
  • name 字段的注释应该记录资源模式。
  • The request message must not contain any other required fields, and should not contain other optional fields except those described in another AIP.
  • 请求消息不得包含任何其他必填字段，并且不应包含其他可选字段，除了另一个 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. Note:请求对象中的 name 字段对应于 RPC 上的 google.api.http 注释中的name 变量。 当使用 REST/JSON 接口时，这会导致根据 URL 中的值填充请求中的name字段。

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. 如果用户没有访问资源的权限，无论它是否存在，服务必须错误并显示 PERMISSION_DENIED (HTTP 403)。 必须在检查资源是否存在之前检查权限。

If the user does have proper permission, but the requested resource does not exist, the service must error with NOT_FOUND (HTTP 404). 如果用户确实拥有适当的权限，但所请求的资源不存在，则服务必须错误并显示“NOT_FOUND”（HTTP 404）。

Changelog

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