各大云厂商的 API 设计风格
目录
说明
没想到各大公有云厂商的 API 是这么乱糟糟的，自家不同服务的风格都不统一。
AWS
AWS 的 API 设计的借鉴价值最低。它较早期的服务 API 没有使用 REST 风格，较新的服务的 API 又开始采用 REST 风格。文档写的很烂很烂，比如 EKS 等使用新的 API 风格，但从文档里完全看不出以前的 Action、api-version 等通用参数是否还需要。 国内的阿里云/腾讯云等明显抄了 AWS 的早期设计，AWS 自家风格都乱了，还跟着瞎抄。 AWS 的 API 做成这个样子，丝毫不影响它成为公有云市场的 No1，值得思考。
AWS：RunInstances
AWS: RunInstances 应该是 aws 最早的 api 之一。文档里没有明确提到的认作未使用，比如文档里没有提 http method，就认为是不区分（这个判断可能不对）。风格如下：
- 不区分 http method，用 Action 参数指定操作：https://ec2.amazonaws.com/?Action=RunInstances
- 参数全都是 query 参数，不支持路径参数
- 通过公用参数 Version 指定 API 版本
- 错误码位于 Response 的 body 中，http reponse code 可能全都是 200
- 借助 client token 实现幂等
https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-beb0caec
&InstanceType=m1.large
&MaxCount=1
&MinCount=1
&KeyName=my-key-pair
&NetworkInterface.1.DeviceIndex=0
&NetworkInterface.1.PrivateIpAddresses.1.Primary=true
&NetworkInterface.1.PrivateIpAddresses.1.PrivateIpAddress=10.0.2.106
&NetworkInterface.1.PrivateIpAddresses.2.Primary=false
&NetworkInterface.1.PrivateIpAddresses.2.PrivateIpAddress=10.0.2.107
&NetworkInterface.1.PrivateIpAddresses.3.Primary=false
&NetworkInterface.1.PrivateIpAddresses.3.PrivateIpAddress=10.0.2.108
&NetworkInterface.1.SubnetId=subnet-a61dafcf
&AUTHPARAMS
AWS EKS: UpdateClusterVersion
AWS EKS: UpdateClusterVersion 还有 AWS Lambda 等换了另一种风格，更像 REST：
- 区分 http method，为 uri 添加
/动词后缀进一步区分 http method 无法表达的操作，Action 等参数文档也没说是否取消 - 按照 http method 使用 query 参数或者 body
- api-version 也没有提及，感觉应该还是使用
- 复用 http status code
Azure
Azure 在全平台 API 风格统一方面也好不到哪去，整体在趋向统一，主流的是 Azure: Virtual Machines Create Or Update 的做法：
- 区分 http method，为 uri 添加
/动词后缀进一步区分 http method 无法表达的操作 - 同时使用 query 参数、路径参数和 body 数据，有不同定位：query 参数是公用参数，路径参数是用于资源定位，body 承接其它参数
- 通过公用参数 api-version 指定版本: api-version=2023-03-01，日期映射到具体的 Major.Minor 版本号
- 复用 http status code，用 ApiError 标识具体错误
微软出了一份 Microsoft REST API Guidelines，在 Versioning 中提到 api group version 可以是日期形式，但是系统内部要将其映射到 Major.Minor 版本号。并且发布新版本后，需要提供历史版本的接口文档。
这方面 azure 做的比较 aws 要好，aws 的 API 完全不知道有多少个版本，每个版本的差异是什么。
Google Cloud
Google Cloud: Creates an instance resource：
- 区分 http method，为 uri 添加
/动词后缀进一步区分 http method 无法表达的操作（注意这是早期做法，现在用:动词后缀） - 同时使用 query 参数、路径参数和 body 数据用：其中路径参数用于资源定位，query 似乎通常是共用/简单的参数，body 数据是主体
- 通过 uri 中 /v1 样式的前缀区分 api 版本
- instances.insert 没有具体说明错误码，应当也是 http status code 和具体的 Error 结合
Google 也有一份 RESTful API Guidelines，它也没有完全遵守，应该是部分接口的实现早于规范的原因：
POST https://compute.googleapis.com/compute/v1/projects/{project}/zones/{zone}/instances/{instance}/detachDisk
// 按照 Google 的 Guidelines 应该是下面样式，用 : 分割动词
POST https://compute.googleapis.com/compute/v1/projects/{project}/zones/{zone}/instances/{instance}:detachDisk
新接口比如 projects.locations.batchPredictionJobs.cancel 采用的是规范：
POST https://{service-endpoint}/v1/{name}:cancel
总结
整体来看接口风格都在往 REST 靠齐， Google 的 RESTful API 设计规范 和微软的 REST API Guidelines 也有很多共同的地方。 不过 Azure 和 AWS 用日期字符串作为版本，我感觉这是奇葩设计，日期做版本会鼓励 API 版本滥发而且用户用的时候要指定日期，更倾向于 Google 通过 /v1 区别版本的方式。
Google 对待 API 更重视，除了发布 RESTful API 设计规范，还发起了一个 API 改善计划：API Improvement Proposals。发起人 JJ Geewax 还在 2021 年初出版了《API Design Patterns》对 API 设计规范进行解释。
参考
- 李佶澳的博客
- Amazon EC2 Common query parameters
- Azure: Virtual Machines Create Or Update
- Google Cloud: Creates an instance resource
- AWS: RunInstances
- Microsoft REST API Guidelines
- Google 是如何实践 RESTful API 设计的？
- Google Method: projects.locations.batchPredictionJobs.cancel
- AWS EKS: UpdateClusterVersion
- AWS Lambda
- Google: API Improvement Proposals
