最佳实践：更好的设计你的 REST API
由于 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 /航班信息/CA827/entry
&id& CA827 &/id&
&link href="航班信息 /CA827/entry" rel="self"/&
&title type="text"&CA827 &/title&
&published&T02:35:40.937Z &/published&
&updated&T02: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 请求：
/developerworks/mydeveloperworks
/files/form/anonymous/api/communitylibrary
/0a7c97bb-6cf9-4ddb-a918-d/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 格式数据：
/developerworks/mydeveloperworks
/files/form/anonymous/api/tags/feed?format=xml
&scope=document&pageSize=30&sK=cloud&sO=dsc
REST API 请求，要求返回 JSON 格式数据：
/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 运行结果，并采取相应动作。 下表列出了比较常用的响应代码。表 1. 常用 HTTP 响应代码含义HTTP 响应代码代码含义
已创建，请求成功且服务器已创建了新的资源。
是否只显示处于警告状态的应用实例
重定向 , 请求的网页已被永久移动到新位置。服务器返回此响应时，会自动将请求者转到新位置。
重定向 , 请求的网页临时移动到新位置，但求者应继续使用原有位置来进行以后的请求。302 会自动将请求者转到不同的临时位置。
未修改，自从上次请求后，请求的网页未被修改过。服务器返回此响应时，不会返回网页内容。
错误请求 , 服务器不理解请求的语法。
未授权 , 请求要求进行身份验证。
已禁止 , 服务器拒绝请求。
未找到 , 服务器找不到请求的网页。
方法禁用 , 禁用请求中所指定的方法。
不接受 , 无法使用请求的内容特性来响应请求的网页。
请求超时 , 服务器等候请求时超时。
已删除 , 如果请求的资源已被永久删除，那么，服务器会返回此响应。
未满足前提条件 , 服务器未满足请求者在请求中设置的其中一个前提条件。
不支持的媒体类型 , 请求的格式不受请求页面的支持。
内部服务器错误。
使用 HTTP 头处理缓存和并发缓存和并发处理，从来是大型软件系统设计中的重要组成部分。使用 HTTP 头进行缓存处理在 REST 的构架中，我们除了在与后台的数据交换中，需要有一个良好的缓存机制外，针对 REST API 请求都是在远端用 HTTP 发起这一特点，还需要为网络缓存进行更多考虑。通过减少 HTTP 响应内容，避免不必要的 HTTP 连接等方式，达到提高 REST API 使用效率的目的。HTTP 头中，有多个字段可以用于缓存处理。比较常用的有缓存控制和条件请求。缓存控制：缓存控制通常是需要客户端，缓存服务器 / 代理服务器与业务服务器一起发生作用。HTTP 头中有“Cache-control”字段来控制如何使用缓存，常见的取值有 private、no-cache、max-age、must-revalidate 等。比如当你给返回的数据内容设置 max-age=600，那么当用户隔了 30 秒再次请求的时候，就不会导致重新请求后台数据。另外，也可以通过“Expires”字段来指定内容过期时间，在此时间前的请求都不会导致后台程序重新请求数据。下图展示了 max-age 是如何工作的。图 2. 缓存控制工作方式的简单范例条件请求与电子标签：很多时候，数据内容可能会几个小时甚至几天都不会发生变动，这个时候根据请求时间间隔来控制缓存，就不能满足系统的需求了。通过支持条件请求与电子标签，可以帮助我们来解决这个问题。当用户请求数据内容时，系统在返回数据的同时，在 HTTP 头中，将返回根据服务器内容的最后修改时间 Last-Modified，或者根据服务器内容生成电子标签 ETag。 当用户再次请求数据时，就可以在 HTTP 请求中使用 If-Modified-Since 或者 If-None-Match 头信息，把上次请求得到的时间戳或者电子标签传给服务器。当收到一个有条件请求的 HTTP 头的 REST 请求的时候，我们的程序需要将收到的时间戳或者电子标签与当前内容作比较，就可以很容易的知道用户请求的数据内容在这段时间是否发生过修改，并根据比较结果返回给用户最新内容，或者用 HTTP 响应码 304 告知用户，内容没有变化。下面是一个来自 IBM developerWorks 的 API 样例，尝试请求该 API，你可以看到该 API 会在 HTTP 头中返回电子标签和缓存处理信息。清单 4. IBM developerWorks 的带有电子标签的文件服务 API REST API 请求：
/developerworks/mydeveloperworks
/form/anonymous/api/communitylibrary
/7e2e8015-bf72-43b6-bacd-36565b67febc/document
/ddc0ef4e-224e-449c-bb2c-f919fafb17d2
/entry?acls=true&includeRecommendation=true
&includeTags=false&includeLibraryInfo=true&format=xml使用 HTTP 头进行并发处理上文我们提到了使用条件请求控制缓存，其实我们还可以使用条件请求进行并发处理。比如当用户 Alice 和 Bob 通过 REST 获取了一篇文档。Bob 阅读文档之后，通过 PUT 来修改文档；而此前几分钟，Alice 刚刚修改了这篇文档，于是 Bob 就在毫不知情的情况下不慎覆盖了 Alice 的修改。通过在写操作中支持条件请求，我们可以更好的处理并发修改。用户在发出修改请求的同时，在 HTTP 请求中使用 If-Not-Modified-Since 或者 If-Match 头信息，把获取数据时得到的时间戳或者电子标签传给服务器；我们的程序通过与服务器当前内容的比较，就可以知道，这个修改请求是否是针对当前内容提出的。当服务器发现内容已经被其他用户修改过了，就不会执行修改请求，并返回 HTTP 响应码 412（未满足前提条件）给用户。下图展示了使用条件请求和电子标签进行并发处理是如何工作的图 3. 支持条件请求时的并发处理简单范例更好的使用数据冗余和链接元素在 ATOM 文档中，我们用各种数据元素来传递信息。其中有一类元素叫做链接，可以用于开发者的进一步访问。通常，我们会提供编辑当前资源的链接，访问当前资源的链接，等等。通过更加灵活的使用这类链接元素，以及提供必要的数据冗余，我们可以大大简化开发者的编程逻辑，提高 REST API 的使用效率 。首先，让我们来看看数据冗余的例子：我们在一个航班信息的文档中，通常会包括飞机的型号；而我们可能经常需要在显示航班信息的时候，同时显示更多的飞机信息（如单通道还是双通道，载客人数等）。这个时候，我们就需要对飞机型号的资源再发起一次请求，才能获得我们需要的信息。如果我们可以在请求航班信息的时候，返回飞机型号的同时获得更多的该型号的信息，就可以减少一次网络连接。为了保证 API 的灵活与效率，我们可以提供一个开关参数，如 includeAircraftDetail=true。其次，让我们来看看链接元素的例子：我们要展示一个文件夹下面所有的文件，并允许用户察看每个文件都允许哪些人编辑，哪些人下载以及将某文件放入收藏夹。这时候，我们可以考虑将这些可以执行的操作的 API 都用链接元素的方式返回给客户端，这样，开发者无需自己拼接 API 调用的 URL，就可以使用，从而降低代码复杂度。清单 5. 一个简单的使用链接元素的样例 REST API 请求：
GET /doc/docID12345/entry
&id& docID12345&/id&
&link href="doc/docID12345/entry" rel="self"/&
&title type="text"&Doc Title &/title&
&published&T02:35:40.937Z &/published&
&updated&T02:35:40.937Z &/updated&
&atom:link doc:rel="reader"
href="/doc/docID12345/reader/feed"
rel="related" type="application/atom+xml"/&
&atom:link doc:rel="editor"
href="/doc/docID12345/editor/feed"
rel="related" type="application/atom+xml"/&
&atom:link ca:rel="collect"
href="/doc/collect?Add=docID12345"
rel="related" type="application/atom+xml"/&&/entry&更多的需要注意的细节与技巧除了以上提到的方面，还有大量的细节与技巧，可以帮助我们更好的设计 REST API：批量更新：当用户需要更新多个资源的时候，你打算让开发者一次次的发送 HTTP 请求逐个更新吗？你可以考虑在设计 API 的时候允许客户同时创建或者更新多个资源。REST 安全：除了使用固有的 HTTP 基本验证，你还可以考虑通过支持表单验证，LTPA 验证，Open ID 验证等方式，来满足更多的企业安全要求。文档服务：是否由于 API 持续更新，使得客户端连接不同版本服务的时候疲于奔命？尝试着把你的 API 定义规范成 XML 文档，这样客户端很容易理解当前服务可以提供哪些功能，以及如何使用这些功能。你还可以通过阅读其他文档得到更多这方面的指导，本文无法将所有的细节与技巧一一穷尽。总结通过以上的经验介绍和技巧举例，我们学习到了如何应用最佳实践来更好的设计 REST API。我们注意到，由于 REST API 主要针对网络应用， 并且大量调用来自于浏览器脚本，因此在细节上有很多自己独特的需要注意的技巧。此外，由于 REST 越来越成为一种系统设计的原则与构架，也要求我们的程序开发人员在设计 API 的时候需要用构架师的视角与高度来思考。希望本文能够帮助您打开 REST API 设计的思路，摸索和总结出更多的技巧，与广大开发人员分享。
阅读 RFC 文档，以了解 HTTP 1.1 标准：
阅读 RFC 文档，以了解 URI 标准：
阅读 HTTP 响应状态码相关文档，以了解标准的状态码，包括可以执行的后续方法以及响应需要的信息：
阅读 developerWorks 文章：认识 Atom 发布协议 -- 使用 Atom 发布协议创建和编辑 Web 资源， 以学习 ATOM 协议的基本知识：
阅读 developerWorks 文章 : 基于 REST 的 Web 服务，以学习 REST 的基础知识：
阅读 developerWorks 文章 : 编写 REST 服务 -- 使用 Java 技术和 Atom 发布协议创建 REST 服务 , 以学习如何开发 REST 服务：
访问 developerWorks 专栏 : REST 与 Web 开发 ，以学习更多 REST 开发的知识：
访问，以获得更多关于如何开发 Web 服务应用程序的文章以及入门级、中级和高级教程
：通过专门关于 Web 技术的文章和教程，扩展您在网站开发方面的技能。：这是有关 Ajax 编程模型信息的一站式中心，包括很多文档、教程、论坛、blog、wiki 和新闻。任何 Ajax 的新信息都能在这里找到。，这是有关 Web 2.0 相关信息的一站式中心，包括大量 Web 2.0 技术文章、教程、下载和相关技术资源。您还可以通过
栏目，迅速了解 Web 2.0 的相关概念。
添加或订阅评论，请先或。
有新评论时提醒我
static.content.url=/developerworks/js/artrating/SITE_ID=10Zone=Web developmentArticleID=631858ArticleTitle=最佳实践：更好的设计你的 REST APIpublish-date=牛皮癣诊断的常用方法
牛皮癣诊断的常用方法
(C)2017 列表网&琼ICP备号-12&增值电信业务经营许可证B2-&383被浏览20504分享邀请回答757 条评论分享收藏感谢收起int id = 10000; // 假设请求的参数为 id ，假设为 10000
int tm = System.currentTimeMillis() / 1000;
String sign = md5(id + tm + "salt"); // md5 是实现取 md5 值（32 字节的 Hex 文本）的函数，salt 是加密盐，建议修改长一点。
String api = "/api?id=" + id + "&tm=" + tm + "&sign=" +
// 请求 API
算法加密字符串形式。和上面的 MD5 差不多，只不过是把参数用 AES / DES 之类的对称或者非对称算法加密之后作为一个验证参数。服务器接到请求之后，解密参数，看看是否正确。这里面还可以加入一些客户端的本地信息作为判断依据。优酷和腾讯视频就是采用的此形式。3. 本地加密混淆。上面第 2 点提到的验证参数，不建议直接放到本地代码里面。不管是 Android 里面的 Java 代码，还是 Flash 里面的 AS 代码，都非常容易被反编译，非常简单就可以看到源代码。所以要放到独立的模块中去。优酷土豆、腾讯视频等，都是使用的此技术。对于 Android 程序，我建议把加密的部分放到 so （C 动态库）文件中去，这样的话破解者即使想破解，也得用上反汇编工具。对 so 文件，两个建议：函数结构要混淆，函数名要混淆，入口点不要用默认的；so 文件要做验证！一定要做验证，否则破解者根本不用破解，直接拿你的 so 文件去使用，你就相当于直接给他写好盗链模块了…对于 Flash，建议使用 FlasCC（Alchemy）技术，将 C 模块植入，这比上面的 so 文件更难破解，打开过很多 Alchemy 技术的 Flash 文件，头都大了。4.服务器端简单限制。在 Web API 的服务器端也有必要做一些简单的限制。User-Agent 和 Referer 限制。限制这些作用不大，但能有效地防止 Web 端直接盗链。除非对方实现了 Socket，但有这个技术的话，何必还来盗链你呢~验证登录。这里所说登录不一定是账户登录，还可以是设备 device 登录。可以给用户设备分配一个唯一的 device id，用来验证。这些信息可以放在 Cookie 里，也可以直接作为一个参数。请求频次限制。对单个 device id 可以设置其请求频率，device id 很容易伪造，所以建议服务器生成，本地只记录和传递。另外上面有些答主提到了 IP 频率限制。我不建议对 IP 进行太多的限制，如果限制频率太低，这会影响正常用户使用，因为国内运营商环境复杂，很多用户共用一个出口 IP 的现象非常常见。但也千万别因此就相信了 HTTP Header 中的 X-Forwarded-For，这个参数是可以直接伪造的。返回的结果可以加密。然后客户端在本地进行解密，解密的代码最好也放到 so 文件中去。5. 定期检查访问日志。上面提到，不建议对 IP 进行限制，那怎么办呢？请务必定期检查服务器的访问日志，这样可以很容易筛选、排查出异常 IP。找出异常流量的 IP 之后，上网搜索一些这些 IP，判断是不是有服务器在盗链，然后 ban 掉它们（其实一开始就可以先找到阿里云、百度云、新浪云等云厂商的 IP 范围，先把他们屏蔽）。最后，要是对方完全破解了你的防盗链措施，并且在客户端完全模拟你客户端的行为的话。那我还能说什么呢…只能说你的产品非常有价值。522 条评论分享收藏感谢收起查看更多回答