Google API Design Guide 笔记

Google API Design Guide 笔记

简介

在新项目框架搭建的初期，在如何制定接口设计规范问题上卡了壳，经过调研多种接口风格，最后选择了Google API Design Guide
，以下为学习笔记。

文档中的规范对要求级别的定义有（“必须”、“不得”、“必需”、“应”、“不应”、“应该”、“不应该”、“建议”、“可以”和“可选”）
具体定义见 RFC 2119。

面向资源的设计

设计流程

• 确定 API 提供的资源类型。
• 确定资源之间的关系。
• 根据类型和关系确定资源名称方案。
• 确定资源架构。
• 将最小的方法集附加到资源。

资源

面向资源的 API 通常被构建为资源层次结构，其中每个节点是一个“简单资源”或“集合资源”。

• 一个集合包含相同类型的资源列表。 例如，一个用户拥有一组联系人。
• 资源具有一些状态和零个或多个子资源。 每个子资源可以是一个简单资源或一个集合资源。
  例如，每个用户都有一组标签、一个个人资料资源和若干设置资源。

方法

面向资源的 API 的关键特性是，优先强调资源而不是方法。方法可以是标准方法或自定义方法。标准方法有：List、Get、Create、Update
和 Delete。

如果 API 功能能够自然映射到标准方法，则应该使用该标准方法。对于不能映射到标准方法的功能，可以
使用自定义方法。自定义方法可用于实现常见的编程模式，例如数据库事务或数据分析。

示例

每个用户都拥有以下资源。

• 消息集合：users//messages/。
• 线程集合：users//threads/。
• 标签集合：users//labels/。
• 变更历史记录集合：users//history/。
• 表示用户个人资料的资源：users/*/profile。
• 表示用户设置的资源：users/*/settings。

资源名称

资源名称由集合 ID 和资源 ID 构成，按分层方式组织并以正斜杠分隔。如果资源包含子资源，则子资源的名称由父资源名称后跟子资源的
ID 组成，也以正斜杠分隔。

示例：电子邮件服务具有一组 users。每个用户都有一个 settings 子资源，而 settings 子资源拥有包括 customFrom 在内的许多其他子资源：

API 服务名称	集合 ID	资源 ID	资源 ID	资源 ID
//mail.googleapis.com	/users	/name@example.com	/settings	/customFrom

标准方法

标准方法即 List、Get、Create、Update 和 Delete

标准方法	HTTP 映射	HTTP 请求正文	HTTP 响应正文
List	GET <collection URL>	无	资源*列表
Get	GET <resource URL>	无	资源*
Create	POST <collection URL>	资源	资源*
Update	PUT or PATCH <resource URL>	资源	资源*
Delete	DELETE <resource URL>	不适用	Empty**

*如果方法支持响应字段掩码以指定要返回的字段子集，则方法返回的资源可能只包含部分数据。

** 不立即移除资源的 Delete 方法（例如软删除或长时间运行的删除操作）返回的响应应该包含长时间运行的操作或修改后的资源。

自定义方法

有一些操作的并不能用标准方法实现，比如审批通过一条数据，此时需要自定义方法。自定义方法是指5个标准方法之外的方法。

https://service.name/v1/some/resource/name:customVerb

定义自定义方法时，应遵循以下准则：

1. 应该使用 POST 方法。
2. 自定义方法不应该使用 PATCH，但可以使用其他 HTTP 动词。方法必须遵循该动词的标准 HTTP 语义。
3. 使用 GET 的自定义方法必须具有幂等性并且无负面影响。
4. 与自定义方法关联的资源名称应该映射到网址路径。
5. 路径必须以包含冒号（后跟自定义动词）的后缀结尾。
6. 如果 HTTP 动词允许请求体（POST、PUT、PATCH 或自定义 HTTP 动词），则请求参数应放到请求体
7. GET、DELETE 方法不得使用请求体

错误

重试错误

客户端可能使用指数退避算法重试 503 UNAVAILABLE 错误。 除非另有说明，否则最小延迟应为 1 秒。 除非另有说明，否则默认重试重复应当仅一次。

对于 429 RESOURCE_EXHAUSTED 错误，客户端可能会在更高层级以最少 30 秒的延迟重试。此类重试仅对长时间运行的后台作业有用。

对于所有其他错误，重试请求可能并不适用。首先确保您的请求具有幂等性

传播错误

如果服务端依赖其他服务，不应将调用产生的错误传播给客户端。例如，服务端调用其他服务时收到 400
INVALID_ARGUMENT 错误，应该将 500 INTERNAL 返回给客户端。

生成错误

服务端应该生成规范的错误信息，帮助客户端开发者理解服务端错误。错误信息中不得包含敏感信息。

HTTP	gRPC	错误消息示例
400	INVALID_ARGUMENT	请求字段 x.y.z 是 xxx，预期为 [yyy, zzz] 内的一个。
400	FAILED_PRECONDITION	资源 xxx 是非空目录，因此无法删除。
400	OUT_OF_RANGE	参数“age”超出范围 [0,125]。
401	UNAUTHENTICATED	身份验证凭据无效。
403	PERMISSION_DENIED	使用权限“xxx”处理资源“yyy”被拒绝。
404	NOT_FOUND	找不到资源“xxx”。
409	ABORTED	无法锁定资源“xxx”。
409	ALREADY_EXISTS	资源“xxx”已经存在。
429	RESOURCE_EXHAUSTED	超出配额限制“xxx”。
499	CANCELLED	请求被客户端取消。
500	DATA_LOSS	服务端错误，不得发送到客户端。
500	UNKNOWN	服务端错误，不得发送到客户端。
500	INTERNAL	服务端错误，不得发送到客户端。
501	NOT_IMPLEMENTED	方法“xxx”未实现。服务端错误，不得发送到客户端。
503	UNAVAILABLE	服务端错误，不得发送到客户端。
504	DEADLINE_EXCEEDED	服务端错误，不得发送到客户端。

未完待续

---

本文的部分内容是在 Google 创建及分享的基础上创作而成，使用时须遵循知识共享 4.0 署名许可中所述条款。