• 一般设计模式
    • 空白响应
    • 表示范围
    • 资源标签
    • 长时运行的操作
    • 列表分页
    • 列出子集合
    • 从子集合获取唯一资源
    • 排序顺序
    • 请求验证
    • 请求重复
    • 枚举默认值
    • 语法句法
    • 整数类型
    • 部分响应
    • 资源视图
    • ETags
    • 输出字段

    一般设计模式

    空白响应

    标准的 Delete 方法必须返回 google.protobuf.Empty 才能获得全局一致性。它还可以防止客户端重试时所依赖的元数据不可用。对于自定义方法，它们必须有自己的形如 XxxResponse 的消息，即使它们是空白的，因为很可能在方法功能变化后，需要返回额外的数据。

    表示范围

    用来表达范围的字段应当使用半开区间的命名约定，形如：[start_xxx，end_xxx)，例如 [start_key，end_key] 或 [start_time，end_time)。 C++ STL 库和 Java 标准库通常使用这种半开区间语义。API 应避免使用其他表示范围的方法，例如 (index，count) 或 [first，last]。

    资源标签

    在面向资源的 API 中，资源模式由 API 来定义。为了让客户端将少量的简单元数据附加到资源（例如，将一个虚拟机标记为数据库服务器），API 应该使用 google.api.LabelDescriptor 中描述的资源标签设计模式。

    为此，设计 API 时应该向资源定义中添加字段 map<string，string> 标签。

    1. message Book {
    2.   string name = 1;
    3.   map<string, string> labels = 2;
    4. }

    长时运行的操作

    如果一个 API 方法通常需要很长时间才能执行完成，那么它可以设计成向客户端返回一个长时间运行（Long Running Operation）资源，客户端可以使用该资源来跟踪进度并获取结果。该操作定义了一个标准接口，用于长时间运行的操作。各个 API 禁止为长时间运行的操作定义自己的接口，以避免不一致。

    操作资源必须作为响应消息直接返回，并且操作的任何直接后果都应该反映在API中。例如，在创建资源时，尽管资源应该指示它没有准备好被使用，该资源也应该出现在LIST和GET方法中。操作完成后，如果方法不长时间运行，Operation.response字段应包含直接返回的消息。

    列表分页

    以列表形式获取的集合应该支持分页，即使结果集通常很小。

    原理：即使向现有的 API 添加分页支持仅仅是从 API 表面视角添加，那也是一个会破坏 API 行为的更改。现有的客户端由于不知道分页，将错误地假设会接收到完整的列表结果，而实际客户端只接收到第一页。

    为了使 List 方法支持分页（在页面中返回列表结果），API 应该：

    • 在 List 方法的请求消息中定义一个 string 类型字段 page_token。客户端使用此字段请求列表结果的特定页面。
    • 在 List 方法的请求消息中定义一个 int32 类型字段 page_size。客户端使用此字段指定服务器一次返回的最大结果数。服务器仍然可以进一步限制在单个页面中返回的结果的最大数量，如果 page_size 为0，服务器将决定要返回的结果数。
    • 在 List 方法的响应消息中定义一个 string 字段 next_page_token。此字段代表用于检索下一页的分页令牌。如果值为空字符串，则表示没有更多结果了。

    要检索下一页结果，客户端应该在后续 List 方法调用（在请求消息的 page_token 字段中）传递前一次响应的 next_page_token 的值：

    1. rpc ListBooks(ListBooksRequest) returns (ListBooksResponse);
    3. message ListBooksRequest {
    4.   string name = 1;
    5.   int32 page_size = 2;
    6.   string page_token = 3;
    7. }
    9. message ListBooksResponse {
    10.   repeated Book books = 1;
    11.   string next_page_token = 2;
    12. }

    当客户端传递除页面令牌之外的查询参数时，如果查询参数与页面令牌不一致，则服务必须使请求失败。

    页面令牌的内容应该是一个 base64 编码过的PB(protocol buffer)。 这避免了兼容性问题，如果页面令牌包含潜在的敏感信息，那么该信息应该被加密。 同时服务必须防止通过以下方法篡改页面令牌以泄露数据：

    • 在后续请求时必须重新指定查询参数。
    • 在页面令牌中只引用服务器端的会话状态。
    • 页面令牌中加密并签名的的查询参数，需要在每次调用时都重新验证和重新授权。

    分页的具体实现中也可以提供名为 total_size 的 int32 字段来表示总数。

    列出子集合

    有时，API 需要让客户端在子集合之间执行List/Search方法。例如，图书馆 API 有一组书架，每个书架都有一组书籍，而客户想要在所有书架上搜索一本书。在这种情况下，建议对子集合使用标准List方法，并为父集合指定通配符集合标识“-”。对于 Library API 示例，我们可以使用以下 REST API 请求：

    GET https://library.googleapis.com/v1/shelves/-/books?filter=xxx

    注意：使用“-”而不是“*”的原因是为了避免需要进行URL转义。

    从子集合获取唯一资源

    有时，子集合中的一个资源具有在其父集合内唯一的标识符。在这种情况下，允许通过 Get 来检索它并且不需要知道其属于哪个父集合。同时，建议使用标准 Get，并为所有父集合指定通配符集合标识“-”。例如，在图书馆 API 中，如果图书在所有书架上的所有图书中是唯一的，则可以使用以下 REST API 请求：

    GET https://library.googleapis.com/v1/shelves/-/books/{id}

    上面这个请求的响应中的资源必须使用资源的规范名称，对于每个父集合，应使用实际父集合标识符而不是“-”。例如，上面的请求应该返回资源名为 shelves/shelf713/books/book8141，而不是 shelves/-/books/book8141。

    排序顺序

    如果 API 方法允许客户端指定列表结果的排序顺序，请求消息应该包含一个字段：

    string order_by = ...;

    排序字符串值应该遵循 SQL 语法：逗号分隔字段列表。例如：“foo，bar”，默认排序顺序为升序，要为字段指定降序，应该在字段名后附加后缀 “desc”。例如：“foo desc，bar”。

    语法中的冗余空格字符无关紧要。“foo，bar desc” 和 “ foo ，bar desc ” 是等效的。

    请求验证

    如果 API 方法有副作用，并且需要验证请求而避免此类副作用，请求消息应该包含一个字段：

    bool validate_only = ...;

    如果此字段设置为 true，则服务器禁止执行任何副作用逻辑，只能执行特定于实现的与完整请求一致的验证逻辑。

    如果验证成功，则必须返回 google.rpc.Code.OK，任何使用相同请求消息的完整请求都不应返回 google.rpc.Code.INVALID_ARGUMENT。注意，请求可能由于其他错误（如 google.rpc.Code.ALREADY_EXISTS）或由于竞争而失败。

    请求重复

    对于网络 API，幂等 API 方法是更优的选择，因为它们可以在网络故障后安全地重试。然而，一些 API 方法无法容易地实现成幂等的。例如创建资源，并且需要避免不必要的重复。对于这种使用情况，请求消息应该包含唯一的 ID，例如 UUID，服务器将使用该唯一 ID 来检测复制，并确保请求仅被处理一次。

    1. // A unique request ID for server to detect duplicated requests.
    2. // This field **should** be named as `request_id`.
    3. string request_id = ...;

    如果检测到重复请求，则服务器应该返回先前成功请求的响应，因为客户端很可能未收到先前的响应。

    枚举默认值

    每个枚举定义必须以 0 值条目开始，当未明确指定枚举值时，将使用该条目。API 必须在文档中记录如何处理 0 值。

    如果存在默认行为，则应该使用枚举值 0，并且 API 应在文档中记录预期行为。

    如果没有默认行为，则枚举值 0 应该命名为 ENUM_TYPE_UNSPECIFIED，并且应该以错误 INVALID_ARGUMENT 来拒绝使用。

    1. enum Isolation {
    2.   // Not specified.
    3.   ISOLATION_UNSPECIFIED = 0;
    4.   // Reads from a snapshot. Collisions occur if all reads and writes cannot be
    5.   // logically serialized with concurrent transactions.
    6.   SERIALIZABLE = 1;
    7.   // Reads from a snapshot. Collisions occur if concurrent transactions write
    8.   // to the same rows.
    9.   SNAPSHOT = 2;
    10.   ...
    11. }
    13. // When unspecified, the server will use an isolation level of SNAPSHOT or
    14. // better.
    15. Isolation level = 1;

    可以为 0值使用一个惯用名称。例如，google.rpc.Code.OK 是指定缺少错误代码的惯用方法。 在这种情况下，OK 在语义上等同于枚举类型定义中的 UNSPECIFIED。

    在存在内在敏感和安全默认值的情况下，该值可以用于“0”值。 例如，BASIC是资源视图枚举中的“0”值。

    语法句法

    在某些 API 设计中，有必要为某些数据格式定义简单的语法，例如可接受的文本输入。为了在 API 之间提供一致的开发体验并降低学习曲线，API 设计者必须使用 ISO 14977 扩展的巴斯克-诺尔格式（EBNF）句法来定义语法：

    1. Production  = name "=" [ Expression ] ";" ;
    2. Expression  = Alternative { "|" Alternative } ;
    3. Alternative = Term { Term } ;
    4. Term        = name | TOKEN | Group | Option | Repetition ;
    5. Group       = "(" Expression ")" ;
    6. Option      = "[" Expression "]" ;
    7. Repetition  = "{" Expression "}" ;

    注意：TOKEN 代表在语法之外定义的终止符。

    整数类型

    在 API 设计中，不应使用无符号整数类型，例如 uint32 和 fixed32，因为一些重要的编程语言不能很好地支持它们，例如 Java 和 JavaScript，他们可能导致溢出错误。另一个问题是，不同的 API 非常喜欢在同一个场景中混用不匹配的有符号和无符号整数类型。

    当有符号整数类型用于负值无意义的场景（例如尺寸或超时）时，值 -1（且只有 -1）可能用于指代特殊的含义，例如文件结尾（EOF）、无限超时、无限配额以及未知的年龄。这些用法必须清楚地记录在文档中，以避免混淆。API 创建者还应该记录隐式默认值 0 的行为。

    部分响应

    有时，一个 API 客户端只需要响应消息中的特定数据子集。为了支持这样的场景，一些 API 平台提供对部分响应的原生支持。Google API 平台通过响应消息中的字段掩码支持这一特性。对于任何 REST API 调用，都有一个隐式系统查询参数 $fields，它是 google.protobuf.FieldMask 值的 JSON 表示形式。响应消息将在发送回客户端之前由 $field 过滤。 API 平台为所有的 API 方法自动处理此逻辑。

    GET https://library.googleapis.com/v1/shelves?$fields=name

    资源视图

    为了减少网络流量，有时允许客户端限制服务器在其响应中返回的资源的部分，返回资源的视图而不是完整的资源表示形式，这一做法是非常有用的。 API 中的资源视图通过向方法请求添加参数来实现该功能，该参数允许客户端指定需要在响应中接收的资源。

    参数：

    • 应该是 enum 类型
    • 必须命名为 view

    每个枚举值定义了资源的哪些部分（哪些字段）将在服务器的响应中返回。每个视图（view）值应该返回什么样的资源视图是由实现来定义的，同时应该在 API 文档中记录。

    1. package google.example.library.v1;
    3. service Library {
    4.   rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
    5.     option (google.api.http) = {
    6.       get: "/v1/{name=shelves/*}/books"
    7.     }
    8.   };
    9. }
    11. enum BookView {
    12.   // Server responses only include author, title, ISBN and unique book ID.
    13.   // The default value.
    14.   BASIC = 0;
    16.   // Full representation of the book is returned in server responses,
    17.   // including contents of the book.
    18.   FULL = 1;
    19. }
    21. message ListBooksRequest {
    22.   string name = 1;
    24.   // Specifies which parts of the book resource should be returned
    25.   // in the response.
    26.   BookView view = 2;
    27. }

    这个结构将映射成类似下面的 URL 地址：

    1. GET https://library.googleapis.com/v1/shelves/shelf1/books?view=BASIC

    您可以在本设计指南的标准方法一章中找到有关定义方法、请求和响应的更多信息。

    ETags

    ETag 是一个非透明的标识符，允许客户端进行带条件的请求。为了支持 ETag，API 应该在资源定义中包含一个 string 字段 etag，其语义必须与ETag的通用用法相匹配。通常，etag包含由服务器计算出的资源的指纹。有关更多详细信息，请参阅 Wikipedia 和 RFC 7232 规范。

    ETag 可以被强验证或弱验证，其中弱验证的 ETag 前缀为 W/。在此上下文中，强验证意味着具有相同 ETag 的两个资源具有逐字节完全相同的内容和相同的额外字段（例如，Content-Type）。这意味着经过强验证的 ETag 允许缓存部分响应并可以稍后用于组合。

    相反，具有相同弱验证的 ETag 值的资源意味着在语义上等同，但不一定是逐字节相同的，因此不适合于缓存响应。

    例如：

    1. // This is a strong ETag, including the quotes.
    2. "1a2f3e4d5b6c7c"
    3. // This is a weak ETag, including the prefix and quotes.
    4. W/"1a2b3c4d5ef"

    输出字段

    API 可能需要区分由客户端作为输入提供的字段，以及只由服务器返回的特定资源的输出字段。对于仅为输出的字段，字段属性应该在文档中记录。

    注意，如果客户端在请求中对”仅输出字段“设值了，或者客户端指定了仅包含输出字段的 google.protobuf.FieldMask，则服务器必须接受请求，而不会出错。 这意味着服务器必须忽略那些”仅输出字段“。因为客户端通常会重用由服务器返回的资源，并将其作为另一个请求输入。例如，检索到的 Book 资源将在稍后用作 UPDATE 方法的请求。如果服务器验证“仅输出字段“，则客户端需要额外工作以清除这些“仅输出字段”。

    1. message Book {
    2.   string name = 1;
    3.   // Output only.
    4.   Timestamp create_time = 2;
    5. }