Google API 设计指南 - 面向资源的设计

• 原文地址: https://cloud.google.com/apis...

• 当前版本: 2017-02-21

• 翻译日期: 2月24日，2017

• Copyright: Creative Commons Attribution 3.0 License

面向资源的设计

本指南的目标是帮助开发者设计出简介、一致且好用的网络API 。与此同时，此指南也有助于统一基于socket 的RPC API和基于HTTP 的REST API 的设计。

长久以来，人们经过API接口和方法，如CORBA 和Windows COM 来设计RPC API。随着时间流逝，愈来愈多的接口和方法被引入。最终的结果将是数目惊人且各不相同的接口和方法。为了正确的使用它们，开发者不得不得进行仔细的学习，这不只耗时并且易错。

REST风格体系最先在2000年被提出，并被设计为配合HTTP/1.1工做。REST的核心原则是定义可被少量方法进行操做的命名资源。这些资源和方法被称为API 的名词 (nouns) 和动词 (verb)。在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 是一系列个体可描述 (individually-addressable) 的资源（API的名词）的模型。资源能够经过他们的资源名称来说起，并能够经过一个小集合内的方法（即API的动词）来操做。

REST Google API 的标准方法（也被称为REST方法）包括List, Get, Create Update 和Delete。当功能不能轻松地映射到标准方法时，如数据库事务，API设计者也可使用自定义方法（也被称为自定义动词或自定义操做）。

注意： 自定义动词并不意味着建立自定义HTTP动词来实现自定义方法。对于基于HTTP的API，自定义动词会被映射到合适的HTTP动词上。

设计流程

The Style Guide suggests taking the following steps when designing resource- oriented APIs (more details are covered in specific sections below):

本指南建议按照下列步骤来设计面向资源的API（更多细节会在之后具体的章节所描述）。

• 肯定API提供的资源类型

• 查明不一样资源间的关系

• 根据资源的类型和关系，决定资源名称的规范

• 决定资源的范式 (schema)

• 为资源加上方法的最小集合

资源 (Resources)

面向资源的API一般按照资源阶层进行建模，其中每个节点能够是单个简单资源或者是一个资源集合。为了方便，他们一般被分别称为一个资源或者一个集合。

一个集合含有一系列相同类型的资源。好比，一个用户拥有一个联系人集合。一个资源拥有一些状态以及0个或多个子资源 (sub-resource)。每一个子资源能够是简单资源或者是资源集合。举例来讲，Gmail API 有一个用户资源集合，其中每一个用户拥有消息集合，帖子集合，标签集合，一个用户资料资源和若干个用户设置资源。

尽管在存储系统和REST API 之间有一些概念上的一致性，但提供面向资源的API 的服务却不必定要是一个数据库，而且其在解释资源资源和方法时用于很大的灵活性。例如，建立一个日历时间（资源）可能会为与会者建立额外的时间，发送邮件邀请给与会者，预约会议室并更新视频会议日程。

方法（Methods)

面向资源的API 的关键特色是它强调资源（数据模型）甚于做用于资源的方法（功能性）。一个典型的面向资源的API 会暴露大量的仅具备少数方法的资源。方法能够是标准方法，也能够是自定义方法。对于本指南，标准方法是：List, Get, Greate, 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 服务实现了Google Cloud Pub/Sub API, 其定义了下列资源模型：

• API服务: pubsub.googleapis.com

• 主题资源集合: projects/*/topics/*

• 订阅资源集合: projects/*/subscriptions/*

注意： 其它Pub/Sub API 实现可能采用不一样的资源名称范式