Google 公开了用于创建 HTTP 或 RPC API 的 API 设计指南。对于创建连接 Google Cloud Endpoints 的 gRPC API 的开发人员来说，这些设计原则更值得推荐使用。
早在 2014 年，Google 在创建云服务API 或其它服务API 时就开始在内部使用了这些设计指南。指南中探讨了HTTP 或RPC API 的设计。虽然HTTP API（也称为REST API）的优点是公认的，但是它们距离实用尚有时日。Google 推荐RPC 尤其是其变体 gRPC 。据 Google 说，虽然大部分的因特网 API 是 HTTP，但是通常被云服务和服务提供商内部使用的是 RPC，并在数量上远高于 HTTP API。
对于通过方法操作一个或多个资源这样的场景，Google 推荐在设计 RPC API 时使用类 REST 方法。资源（也可称为域实体）使用 URI 表示，也可以在网络路径格式后面加上唯一的名称（ID）。同一类型的资源将组织成同一集合。
使用的标准方法包括Create、Delete、Get、List和Update。对于不能映射到任一标准方法上的操作，例如数据库事务，用户也可以创建自定义方法。推荐使用较少的方法来操作尽可能多的资源。
在创建资源时，推荐执行如下步骤：
- 确定 API 提供的资源类型。
- 确定资源间关系。
- 基于类型和关系确定资源的命名模式。
- 确定资源模式。
- 为资源附加最小的方法集。
Google 使用“语义化版本”标准命名版本，命名使用三个数字，形式为“主版本. 次版本. 补丁”。预发布版本在命名时添加了一个前缀，例如“1.0.0-alpha”。
对于资源、标准、自定义方法、标准域、错误、使用proto3 创建API 等方面，指南提供了更多细节和例子。
查看英文原文： Google Makes Public Their API Design Guide
感谢张卫滨对本文的审校。
给InfoQ 中文站投稿或者参与内容翻译工作，请邮件至 editors@cn.infoq.com 。也欢迎大家通过新浪微博（ @InfoQ ， @丁晓昀），微信（微信号： InfoQChina ）关注我们。
暂无签名
腾讯云云原生提质增效实践精选集 2024
《2024腾讯云云原生提质增效实践精选集》出炉，5大热门技术领域，13个行业精选标杆案例，痛点到解决方案全...
评论