GoogleAPIDesignGuide（⾕歌API设计指南）中⽂版
⾯向资源的设计
这份设计指南的⽬标是帮助开发⼈员设计简单、⼀致、易⽤的⽹络API。同时，它也有助于收敛基于socket的API和（注：原⽂是with，这⾥翻译为“和”）基于HTTP的REST API。
以前，⼈们根据诸如CORBA和Windows COM这样的API接⼝和⽅法设计RPC API。随着时间的推移，接⼝和⽅法越来越多。最后，接⼝和⽅法数不胜数⼜各不相同。开发⼈员要正确使⽤它们，必须仔细了解每⼀个的⽤法，这很浪费时间⽽且容易出错。
2000年，为了与HTTP1.1搭配使⽤，架构风格出现。它的核⼼原则是定义⽤少量⽅法就能操作的命名资源。资源和⽅法可视为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服务：leapis
⼀组⽤户：users/*。每个⽤户有如下资源。
⼀组消息：users/*/messages/*。
⼀组主题：users/*/threads/*。
⼀组标签：users/*/labels/*。
⼀组变更历史：users/*/history/*。
⼀个代表⽤户资料的资源：users/*/profile
⼀个代表⽤户配置的资源：users/*/settings
design翻译
Google Cloud Pub/Sub API
⼀组主题：projects/*/topics/*。
⼀组订阅：projects/*/subscriptions/*。
注意：PUB/SUB API的其他实现可能选⽤了与上⾯不同的命名规则。

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。