• 面向资源的设计
    • 什么是REST API
    • 设计流程
    • 资源
    • 方法
    • 例子
      • Gmail API
      • Google Cloud Pub/Sub API

    面向资源的设计

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

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

    2000年,为了与HTTP1.1搭配使用,REST架构风格出现。它的核心原则是定义用少量方法就能操作的命名资源。资源和方法可视为API的名词动词。在HTTP协议中,资源名称自然地对应于URL,方法则对应于HTTP的POSTGETPUTPATCHDELETE方法。

    在互联网领域,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方法)的标准方法ListGetCreateUpdateDelete。API的设计者也可以用自定义方法(也被称为自定义动词或者自定义操作),来完成那些不易对应到标准方法的功能,比如数据库事务。

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

    设计流程

    设计指南建议使用以下步骤设计面向资源的API(更多细节请参考下面指定章节):

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

    资源

    面向资源的API通常被建模为一个资源层次结构。其中每一个节点可以是一个简单资源也可以是一组资源。为了方便,它们通常被称为资源或者资源组。

    • 资源组包含相同类型的一系列资源。比如,一个用户有一组联系人。
    • 资源有相同的状态,也有零或者多个子资源。每一个子资源可以是单个资源也可是一组资源。

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

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

    方法

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

    当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的其他实现可能选用了与上面不同的命名规则。