AIP-130 方法
·
[tommwq@126.com]
| 编号 | 130 |
|---|---|
| 原文链接 | https://google.aip.dev/130 |
| 状态 | 批准 |
| 创建日期 | 2023-03-13 |
| 更新日期 | 2023-03-13 |
API由若干个方法组成，方法是服务代表消费者执行的特定操作。
指南
方法类别
以下列举了现存的多种方法类别，通常根据方法操作的对象（例如集合或资源）进行分组。
| 类别名字 | 相关AIP | 声明式客户端集成 | CLI/UI集成 | SDK集成 |
|---|---|---|---|---|
| 标准方法 | ||||
| 标准集合方法 操作资源集合（LIST、CREATE） | AIP-121 AIP-132 AIP-133 | 可自动化 | 可自动化 | 可自动化 |
| 标准资源方法 提取或修改单个资源（GET、UPDATE、DELETE） | AIP-121 AIP-131 AIP-134 AIP-135 | 可自动化 | 可自动化 | 可自动化 |
| 批量资源方法 根据名字提取或修改集合中的多个资源 | AIP-231 AIP-233 AIP-234 AIP-235 | 可用于优化查询 | 可自动化 | 可自动化 |
| 聚合列表方法 提取或修改不同集合中的多个同类型资源 | AIP-159 | 不实用，无法可自动化 | 可自动化 | 可自动化 |
| 自定义提取方法 | ||||
| 自定义集合提取方法 从集合中提取无法用标准方法得到的信息 | AIP-136 | 硬编码 | 可自动化 | 可自动化 |
| 自定义资源提取方法 提取无法用标准方法得到的单个资源的信息 | AIP-136 | 硬编码 | 可自动化 | 可自动化 |
| 自定义修改方法 | ||||
| 备份资源 保存资源在特定时间点的副本 | API-162 | 不实用或硬编码 | 可自动化 | 可自动化 |
| 恢复资源 将资源设置为特定时间点的版本 | AIP-162 | 不实用或硬编码 | 可自动化 | 可自动化 |
| 重命名资源 修改资源名字或标识，保留配置和数据 | AIP-136 | 不实用或硬编码 | 可自动化 | 可自动化 |
| 自定义集合修改方法 对集合执行标准方法无法实现的命令式操作，修改其中的若干资源（例如状态转换） | AIP-136 | 不实用或硬编码 | 可自动化 | 可自动化 |
| 自定义资源修改方法 对资源执行标准方法无法实现的命令式修改操作，（例如状态转换） | AIP-136 | 不实用或硬编码 | 可自动化 | 可自动化 |
| 附加自定义方法 | ||||
| 无状态方法 对API中的数据没有永久性影响的方法（例如翻译文本） | AIP-136 | 不实用或硬编码 | 可自动化 | 可自动化 |
| 其他 | ||||
| 流式方法 通过客户端、服务器或双向流进行通信的方法 | 硬编码 | 硬编码 | 可自动化 |
选择方法类别
在设计方法时，API作者应当按以下顺序选择方法类别：
- 标准方法（在集合和资源上）
- 标准批量或聚合方法
- 自定义方法（在集合或资源上、无状态）
- 流式方法
理由
优先推荐面向资源的标准和自定义方法，因为它们可以在最广泛的客户端（声明式客户端、CLI、UI等）中使用，提供最统一的体验，让用户可以将关于一个API的知识应用到另一个。
如果标准方法不合适，自定义方法（挂载于资源或集合上）提供了较低的、但仍有价值的一致性水平，帮助用户理解操作的范围，以及读取哪个对象的配置可以得知操作结果。尽管修改资源的自定义方法的接口不统一，无法与完全面向资源的客户端（如声明式客户端）进行自动化集成，但它们仍然是容易被CLI、UI和SDK识别的模式。
如果完全无法以面向资源的方式表达API，那么它就属于一种缺乏一致性的操作，除了SDK之外，任何客户端都难以对操作进行建模。这种操作往往作为最后的选择，因为用户无法复用他们对类似API的已有知识。同时，与许多客户端的集成也往往需要手动编码。
修订记录
- 2023-09-05 将状态改为批准。