Google API Design Guide (谷歌API设计指南)中文版

面向资源的设计

这份设计指南的目标是帮助开发人员设计简单、一致、易用的网络API。同时，它也有助于收敛基于socket的API和（注：原文是with，这里翻译为“和”）基于HTTP的REST API。

之前，人们根据诸如CORBA和Windows COM这样的API接口和方法设计RPC API。随着时间的推移，接口和方法愈来愈多。最后，接口和方法数不胜数又各不相同。开发人员要正确使用它们，必须仔细了解每个的用法，这很浪费时间并且容易出错。

2000年，为了与HTTP1.1搭配使用，REST架构风格出现。它的核心原则是定义用少许方法就能操做的命名资源。资源和方法可视为API的名词和动词。在HTTP协议中，资源名称天然地对应于URL，方法则对应于HTTP的POST、GET、PUT、PATCH和DELETE方法。

在互联网领域，HTTP REST API最近得到了巨大的成功。截至2010年，大约74%的公网API都是HTTP REST API。

尽管HTTP REST API在互联网领域已经很流行了，但其承载的流量仍是比传统的RPC API小。好比，在高峰期，美国大约一半的互联网流量都是视频内容，出于性能上的考虑，不多有人用REST API。在数据中心内部，更多的公司也使用基于socket的RPC API来承载大多数网络流量，这比REST API的数量高出几个量级。

事实上，RPC API和HTTP REST API都有存在的理由。在理想状况下，API平台最好提供这两种API。这份设计指南也是基于这一原则帮你设计和构建API。在通用API设计上，本指南应用面向资源设计的原则，定义了众多常见的设计模式以提升易用性并下降复杂性。

注意：本设计指南解释了如何将REST原则用于独立于编程语言，操做系统或者网络协议的API设计，它不仅是用于建立REST API的指南。

什么是REST API

一组REST API被建模为一组可独立寻址的资源（API的名词）。资源被经过资源名称被引用，经过一小组方法（也被称为动词或者操做）被操做。

Google REST API（也被称为REST方法）的标准方法有List，Get，Create，Update和Delete。API的设计者也能够用自定义方法（也被称为自定义动词或者自定义操做），来完成那些不易对应到标准方法的功能，好比数据库事务。

注意：自定义动词不意味着建立自定义的HTTP动词以支持自定义方法。对于基于HTTP的API来讲，自定义动词被对应到最合适的HTTP动词上。（译者注：不能自创HTTP动词，应该使用含义最接近的HTTP动词去设计API）

设计流程

设计指南建议使用如下步骤设计面向资源的API（更多细节请参考下面指定章节）：

• 肯定一个API提供什么类型的资源
• 肯定资源之间的关系
• 根据资源类型和关系肯定资源命名方案
• 明确资源schema
• 给资源添加最少的方法集

资源

面向资源的API一般被建模为一个资源层次结构。其中每个节点能够是一个简单资源也能够是一组资源。为了方便，它们一般被称为资源或者资源组。

• 资源组包含相同类型的一系列资源。好比，一个用户有一组联系人。
• 资源有相同的状态，也有零或者多个子资源。每个子资源能够是单个资源也但是一组资源。

例如，Gmail API有一组用户，每一个用户有一组消息，一组主题，一组标签，单个用户配置资源或多个设置项资源。

尽管REST API和存储系统有概念上的一致性，但具备面向资源的API的服务不必定是数据库，而且在如何解释资源和方法上有巨大的灵活性。好比，建立一个日历事件（资源）可能会为参会者建立附加事件，向参会者发送邀请邮件，预定会议室，更新视频会议日程表。

方法

面向资源的API的关键特性是强调资源（数据模型）和（译者注：原文看起来是笔误，这里应该翻译为和）运行在资源上的方法（功能）。典型的面向资源的API经过少许方法的暴露大量资源。这些方法能够是标准的或者自定义的。在本指南中，标准方法是指：List,Get,Create,Update和Delete。

当API功能天然地映射到一个标准方法时，这个方法应当用于API设计。若当功能不能天然的映射到标准方法时，能够使用自定义方法。自定义方法能提供与传统RPC API同样的设计自由度，能够用来实现常见的编程模式，好比数据库事务或者数据分析。

例子

接下来，咱们看一看现实中如何使用面向资源的API来设计大规模服务。

Gmail API

Gmail API服务实现了Gmail API，暴露了绝大多数Gmail的功能。它的资源模型以下：

• Gmail API服务：gmail.googleapis.com
• 一组用户：users/*。每一个用户有以下资源。
  • 一组消息：users/*/messages/*。
  • 一组主题：users/*/threads/*。
  • 一组标签：users/*/labels/*。
  • 一组变动历史：users/*/history/*。
  • 一个表明用户资料的资源：users/*/profile
  • 一个表明用户配置的资源：users/*/settings

Google Cloud Pub/Sub API

pubsub.googleapis.com服务实现了Goole Cloud Pub/Sub API，它定义了如下资源模型：

• API服务：pubsub.googleapis.com
• 一组主题：projects/*/topics/*。
• 一组订阅：projects/*/subscriptions/*。

注意：PUB/SUB API的其余实现可能选用了与上面不一样的命名规则。

來源：https://www.bookstack.cn/read/API-design-guide/API-design-guide-02-%E9%9D%A2%E5%90%91%E8%B5%84%E6%BA%90%E7%9A%84%E8%AE%BE%E8%AE%A1.md