AIP-130 方法

编号	130
原文链接	AIP-130: Methods
状态	批准
创建日期	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的已有知识。同时，与许多客户端的集成也往往需要手动编码。