Google API设计指南－资源名称

翻译自 API Design Guide - Resource Names

在面向资源的 API 中，资源是命名实体，资源名称是其标识符。每个资源 必须（ MUST ） 有唯一的资源名称。资源名称由资源自己的 ID，任一父资源的 ID 及其 API 服务名称组成。下面我们将看一看资源 ID 和资源名是如何构成的。

gRPC API 应该为资源名使用无协议（scheme-less）的 URI。它们通常遵循 REST URL 惯例并且其行为与网络文件路径非常相似。它们能非常容易地映射到 REST API：详细内容查看标准方法。

集合是一种特殊类型的资源，它包含了相同类型子资源的列表。例如，目录是文件资源的集合。集合的资源 ID 叫做集合 ID。

资源名称由集合 ID 和资源 ID 按层次组织形成，并以斜杠（/）分隔。如果资源包含子资源，子资源名称的格式是父资源名称后面加上子资源 ID，同样地使用斜杠分隔。

例 1：一个存储服务具有 buckets 集合，每个 bucket 具有 objects 集合：

| API 服务名 | 集合 ID | 资源 ID | 集合 ID | 资源 ID |
| - | - | - | - | - |
| //storage.googleapis.com | /buckets | /bucket-id | /objects| /object-id |

例 2：一个具有 users 集合的邮件服务，每个用户具有 settings 子资源， settings 子资源具有 customFrom 和另外的子资源：

| API 服务名 | 集合 ID | 资源 ID | 资源 ID | 资源 ID |
| - | - | - | - | - |
| //mail.googleapis.com | /users | /[e-mail] | /settings| /customFrom |

API 设计者可以为资源和集合 ID 选择任何可接受的值，只要它们在资源层次结构中是唯一的即可。你可以在下面找到有关选择适当资源和集合 ID 的更多指南。

完整资源名

无协议（scheme-less） URI 由兼容 DNS 的 API 服务名和资源路径组成。资源路径也称为相对资源名。例如：

"//library.googleapis.com/shelves/shelf1/books/book2"

API 服务名用于客户端定位 API 服务端点，如果只为内部服务，它可以（may）是假的 DNS 名。如果 API 服务名在上下文中显而易见的话则会经常使用相对资源名。

相对资源名

没有斜杠（/）开头的 URI 路径标识了 API 服务中的资源。例如：

"shelves/shelf1/books/book2"

资源 ID

使用非空的 URI 段标识其父资源中的资源。请看上面的例子。

资源名称后面跟随的资源 ID 可以（may） 具有不只一个 URI 段，例如：

| 集合 ID | 资源 ID |
| - | - |
| files | /source/py/parser.py |

如果可以的话，API 服务应该（should）使用 URL 友好的资源 ID。资源 ID 必须（must） 明确地记录在文档中，不管它们是由客户端还是服务端分配的。例如，文件名一般由客户端分配，而邮件信息 ID 一般由服务端分配。

集合 ID

使用非空的 URI 段标识其父资源中的资源集合。请看上面的例子。

因为集合 ID 经常出现在生成的客户端库中，它们 必须（must） 符合以下要求：

• 必须（must） 是合法的 C/C++ 标识符

• 必须（must） 是复数形式的首字母小写的驼峰命名

• 必须（must） 使用清晰简明的英语词汇

• 应该（should） 避免或限定过于笼统的术语。例如：RowValue 优于 Value。除非明确定义，否则 应该（should） 避免使用如下术语：

  • Element

  • Entry

  • Instance

  • Item

  • Object

  • Resource

  • Type

  • Value

资源名 vs URL

完整的资源名类似普通的 URL，但它们并不相同。同样的资源能够通过不同版本或不同协议的 API 来暴露出去。完整的资源名并没有指定这些信息，所以必须将它映射到特定的协议和 API 版本上才能直接地使用。

为了通过 REST API 使用完整的资源名，必须（must） 使用如下方法将其映射为 REST URL：在服务名前添加 HTTPS 协议、在资源路径前添加 API 主版本号、将资源路径进行 URL 转义。例如：

// 这是日历事件的资源名
"//calendar.googleapis.com/users/john smith/events/123"

// 这是对应的 HTTP URL
"https://calendar.googleapis.com/v3/users/john%20smith/events/123"

资源名做为字符串

除非有向后兼容的问题，Google API 必须（must） 使用字符串来表示资源名。资源名 应该(should) 像普通文件路径那样处理，并且不支持百分号编码。

对于资源定义，第一个字段 应该（should） 是资源名称的字符串字段，它 应该（should） 叫作 name。

注意：像 display_name、first_name、last_name、full_name 这种与名字相关的字段 应该（should） 给出定义来避免混乱。

例子：

service LibraryService {
  rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
      get: "/v1/{name=shelves/*/books/*}"
    };
  };
  rpc CreateBook(CreateBookRequest) returns (Book) {
    option (google.api.http) = {
      post: "/v1/{parent=shelves/*}/books"
      body: "book"
    };
  };
}

message Book {
  // book 的资源名。必须是"shelves/*/books/*"的格式
  // 例如："shelves/shelf1/books/book2".
  string name = 1;

  // ... 其他属性
}

message GetBookRequest {
  // 一个 book 的资源名。例如："shelves/shelf1/books/book2"
  string name = 1;
}

message CreateBookRequest {
  // 创建 book 的父资源名
  // 例如："shelves/shelf1"
  string parent = 1;
  // 被创建的 book 资源。客户端一定不能（must not）设置 `Book.name` 字段
  Book book = 2;
}

提示：为了资源名称的一致性，开始的斜杠 一定不能（must not） 被 URL 模版变量捕获。例如，必须（must） 使用 URL 模版 "/v1/{name=shelves/*/books/*}" 而不是 "/v1{name=/shelves/*/books/*}"。

查看其他章节