Question

如何更好地设计REST API

Answer 1

　　由于REST可以降低开发的复杂度，提高系统的可伸缩性，增强系统的可扩展性，简化应用系统之间的集成，因而得到了广大开发人员的喜爱，同时得到了业界广泛的支持。比如IBM，Google等公司的很多产品都提段哗猜供了REST API给开发人员；与此同时，大量的开源项目和云计算服务都提供了REST API接口。

　　而在最近，一些新产品的开发甚至已经几乎完全抛弃了传统的类似JSP的技术， 转而大量使用REST风格的构架设计， 即在服务器端所有商业逻辑都以REST API的方式暴露给客户端， 所有浏览器用户界面使用widget、Ajax、HTML5 等技术，用HTTP的方式与后台直接交互。

　　那么， 在REST API爆炸式增长的今天， 我们应该如何更好的设计我们的接口， 来提高我们的API的可芦培用性，易用性，可维护性与可扩展性呢？本文将从以下方面与您探讨REST API设计方面的最佳实践：

　　如何规划资源标识结构与URI模式
　　如何根据应用场景提供内容协商
　　如何正确的使用HTTP响应代码
　　如何处理缓存和并发请求
　　如何利用数据冗余和链接元素
　　先决条件

　　如果您具有如下知识与经验，将有助于您阅读和理解本文章的内容 。

　　REST相关的基本知识；
　　HTTP协议的基本知识；
　　一定的Web开发经验。
　　REST简介

　　REST是英文Representational State Transfer的缩写，是近年来迅速兴起的，一种基于HTTP、URI以及XML这些现有协议与标准的，针对网络应用的设计和开发方式。它可以降低开发的复杂度，提高系统的可伸缩性。

　　REST的核心是可编辑的资源及其集合，用符合Atom文档标准的Feed和Entry表示。每个资源或者集合有一个惟一的URI。系统以资源为中心，构建并提握型供一系列的Web服务。REST的基本概念和原则包括：系统上的所有事物都被抽象为资源；每个资源对应唯一的资源标识；对资源的操作不会改变资源标识本身；所有的操作都是无状态的；等等。

　　在REST中，开发人员显式地使用HTTP方法，对系统资源进行创建、读取、更新和删除的操作：

　　使用POST方法在服务器上创建资源
　　使用GET方法从服务器检索某个资源或者资源集合
　　使用PUT方法对服务器的现有资源进行更新
　　使用DELETE方法删除服务器的某个资源

图 1. 用 HTTP 方法操作相册系统资源的简单范例

　　更好的规划你的资源标识结构与URI模式

　　REST 中，最基本的莫过于资源标识结构和URI模式了。更好的规划他们，是我们的API设计取得成功的最关键的一步。

　　首先，我们来看看基本资源类型

　　上文中提到，在REST构架的设计中，系统中的所有事物都被抽象为资源。

　　在一个文档系统中，文档、目录、注释、草稿等等，是组成系统的资源。

　　在一个银行系统中，客户信息、理财产品、利率信息、网点信息等等，是组成系统的资源。

　　在一个航空客票系统中，旅客信息、机票订单、航班信息、机场信息等等，是组成系统的资源。

　　这些资源，通常在系统中以“Entry”的形式出现。下面的代码样例向您展示了一个常见的“Entry”资源。

　　清单 1. 一个简单的Entry资源样例

以下是引用片段：
REST API 请求：
GET http://example.com/航班信息/CA827/entry
<entry>
<id> CA827 </id>
<link href="航班信息 /CA827/entry" rel="self"/>
<title type="text">CA827 </title>
<published>2010-08-24T02:35:40.937Z </published>
<updated>2010-08-24T02:35:40.937Z </updated>
<ca:from>Beijing </ca:from>
<ca:to>Changsha </ca:to>
<ca:time>09:30:00 </ca:time>
<ca:aircraft>AB330 </ca:aircraft>
<summary type="text"/>
</entry>

　　我们会注意到，这些资源，在描述了某种事物的同时，还有可能存在一定的层次结构关系。比如，文档从属于某个目录，注释从属于文档；旅客信息可以从属于机票订单，也可以从属于某个航班。

　　当我们的资源有这种层次关系的时候，我们不妨在URI模式的设计中，用复合的URI来帮助开发者更好的理解和设计资源。

　　比如， 针对一个文档的评论， 他的URI模式可以设计成如下：/文件夹/[文件夹名]/文件/[文件名]/评论/[ 评论唯一标示 ]。 这样，在构造和解析URI的过程中， 可以帮助开发者更好的理解系统，设计程序。

　　其次，我们来看看集合资源类型

　　资源，除了作为独立个体可以被访问，还可以由多个个体组合成一个集合，在系统中，通常以“feed”的形式存在。资源的集合， 可以是处于相同层次上，有相同从属关系的一组资源，比如一个文件夹下的所有文件； 也可以是根据某种条件查询出来的查询结果的资源集合，比如所有30岁以上40岁以下，拥有100万资产以上客户的名单。

　　下面，我们来讨论一下设计集合类型资源的REST API时需要考虑的问题。

　　使用过滤条件来帮助用户更准确地获取数据

　　我们要返回的资源集合，无论是否有相同从属关系，大部分时候都需要进行必要的过滤，提供足够的过滤参数，查询参数， 能够帮助开发者高效的，准确地获取所需要的数据。 在服务器端过滤数据通常比客户端高效，并且减少了不必要的数据传输，可以大大减少网络开销，提高执行效率。

　　最常见的过滤条件，是通过URL参数实现，比如/环境工程系/学生? 籍贯=北京&性别=女。

　　很多时候，我们需要制定更加复杂的过滤条件，那么我们可以有两种选择：

　　首先，我们可以使用正则表达式或者服务器可以理解的语法，比如/环境工程系/学生?filter=age between (15, 18)

　　其次，我们还可以使用POST方法，携带一个文件来描述复杂的查询条件，文件的格式与语法通常需要在服务器端有相应的设计与定义。不过通常POST方法没有缓存机制，因此不是查询数据的首选。

　　使用排序来帮助客户端更好的展现数据

　　虽然进行客户端排序对于开发者来说是件轻而易举的事情，但是直接得到已经排序的返回结果，仍然是大部分开发者所期望的。尤其是很多时候，我们在浏览器，使用 Widget 展示结果，不适宜在客户端存储大量数据进行内存排序。

　　排序， 通常有2个参数，一个是用来排序的字段，一个是排序的升序降续方式。比如我们可以用支持这样的参数组合的手段，提供基本的排序能力：?sortOrder=asc&sortField=age

　　使用分页来帮助客户端处理大量数据

　　由于返回的结果可能有几百几千条记录，将这些记录一次性的返回给客户端是不现实的，巨大的网络流量开销和客户端数据区的内存开销，都是我们在应用开发的时候不希望看到的，因此，如果你的集合资源有可能有大量的数据返回，请务必提供分页的功能支持。

　　我们通常用一个以上参数来制定一个返回结果的区域，比较常见的有下面两种：

　　一种常见于用固定行数的表格来展示数据，用当前处于第几页和每页返回多少行数据来确定需要的数据， 比如/所有学生?page=5&pagesize=50

　　另外一种常见于用更加灵活的界面展示数据，用从第几行开始，一共返回多少行数据来确定需要的数据， 比如/所有学生?startIndex=27&count=22

　　下面是一个来自IBM developerWorks的API样例，尝试请求该API，你可以看到该集合很好的支持了结果的分页与排序。同时我们从返回的信息中可以看到，每个文档Entry的URI都按照/社区库/[社区库ID]/文档/[文档ID]的复合URI的模式设计的。

　　清单 2. IBM developerWorks的某个社区文件库的集合资源的API

以下是引用片段：
REST API 请求：
GET https://www.ibm.com/developerworks/mydeveloperworks
/files/form/anonymous/api/communitylibrary
/0a7c97bb-6cf9-4ddb-a918-80994e7b444d/feed?
pageSize=5&page=1&sK=modified&sO=dsc

　　最后，我们来讨论一些特殊资源类型

　　理想的REST世界，一切事物都抽象为资源，一切操作都抽象为增删改查。然而，所有事物与操作都可以很容易的按照这个规则作抽象吗？让我们看看这个例子：

　　检入和检出一个文档----这个时候，我们要处理的资源是一个文档，然而增删改查似乎都无法与“检入检出”这个动作进行对应。当然，我们可以在文档资源中，设计一个检入检出状态的元素，通过编辑文档资源来实现。但是，这种设计从自然语义上看，并不是很贴切；并且增加了资源编辑操作的复杂度。

　　如果我们来定义一个新的集合----“我检出的文档”，用创建一个集合资源来对应检出（创建一个文档锁），用删除一个集合资源来对应检入（删除一个文档锁）， 是不是逻辑上可以变得更加清楚？

　　在REST这个以名词为核心的构架结构中，当你遇到一些动词特性比较强的操作，而又很难用原始资源的增删改查来匹配的时候，不妨换个思路， 通过引入新的逻辑资源集合的方式， 来进行API的设计与规划。

　　理解和使用内容协商

　　我们的开发者在发送一个REST API请求的同时，根据应用场景，针对相同的资源，可能会期待不同的返回形式。

　　比如，我希望根据用户客户端语言，同一个资源的内容可以返回不同的语言。又比如，当我使用Java编程的时候，我希望得到ATOM格式的返回结果，而当我使用JavaScript编程的时候，我希望得到Json格式的返回结果。

　　因此，我们在设计REST API的时候，应该提供完备的内容协商能力。

　　使用URL参数进行内容协商

　　最容易想到的自然是通过URL参数进行控制，我们经常看到形如/航班号/entry? format=JSON这样的URL。这种方式的优势就是简单灵活， 你可以通过任何 URL 参数来组合你的输出格式。

　　下面是一个来自IBM developerWorks的API样例，尝试请求该API，你可以看到该集合是如何支持不同的输出格式请求的。

　　清单 3. IBM developerWorks的文件服务标签云的API

以下是引用片段：
REST API请求，要求返回XML格式数据：
GET https://www.ibm.com/developerworks/mydeveloperworks
/files/form/anonymous/api/tags/feed?format=xml
&scope=document&pageSize=30&sK=cloud&sO=dsc
REST API请求，要求返回JSON格式数据：
GET https://www.ibm.com/developerworks/mydeveloperworks
/files/form/anonymous/api/tags/feed?format=json
&scope=document&pageSize=30&sK=cloud&sO=dsc

　　使用Accept头进行内容协商

　　使用URL参数，简单灵活，但是也由此带来了设计上的随意和不标准。并且，过多的参数会导致URL的可读性变差，更有甚者，可能会导致URL过长，超出规范，API请求无法执行。

　　更为标准的内容协商方式是使用HTTP头。我们通常使用Accept来设置我们接受的返回结果的内容格式，用Accept-Charset来设置字符集，用Accept-Encoding来设置数据传输格式，用Accept-Language来设置语言。

　　使用URI模式进行内容协商

　　还有一种模式，就是将协商设置直接作为URI的一部分，将不同的返回视为不同的资源，比如/航班号/json来返回JSON格式的结果，用/航班号/atom来返回ATOM格式的结果。

　　正确的使用HTTP响应代码

　　作为API的设计者，正确的将API执行结果和失败原因用清晰简洁的方式传达给客户程序是十分关键的一步。 我们确实可以在HTTP的相应内容中描述是否成功，如果出错是因为什么， 然而， 这就意味着用户需要进行内容解析，才知道执行结果和错误原因。因此，HTTP响应代码可以保证客户端在第一时间用最高效的方式获知API运行结果，并采取相应动作。

转载，仅供参考，祝你愉快，满意请采纳。