最佳实践：更好的设计你的 REST API
平均分 （共 17 个评分 ）
由于 REST 可以降低开发的复杂度，提高系统的可伸缩性，增强系统的可扩展性，简化应用系统之间的集成，因而得到了广大开发人员的喜爱，同时得到了业界广泛的支持。比如 IBM，Google 等公司的很多产品都提供了 REST API 给开发人员；与此同时，大量的开源项目和云计算服务都提供了 REST API 接口。
而在最近，一些新产品的开发甚至已经几乎完全抛弃了传统的类似 JSP 的技术， 转而大量使用 REST 风格的构架设计， 即在服务器端所有商业逻辑都以 REST API 的方式暴露给客户端， 所有浏览器用户界面使用 widget，Ajax，HTML5 等技术，用 HTTP 的方式与后台直接交互。
那么， 在 REST API 爆炸式增长的今天， 我们应该如何更好的设计我们的接口， 来提高我们的 API 的可用性，易用性，可维护性与可扩展性呢？本文将从以下方面与您探讨 REST API 设计方面的最佳实践：
如何规划资源标识结构与 URI 模式
如何根据应用场景提供内容协商
如何正确的使用 HTTP 响应代码
如何处理缓存和并发请求
如何利用数据冗余和链接元素
?
我们会注意到，这些资源，在描述了某种事物的同时，还有可能存在一定的层次结构关系。比如，文档从属于某个目录，注释从属于文档；旅客信息可以从属于机票订单，也可以从属于某个航班。
当我们的资源有这种层次关系的时候，我们不妨在 URI 模式的设计中，用复合的 URI 来帮助开发者更好的理解和设计资源。
比如， 针对一个文档的评论， 他的 URI 模式可以设计成如下：/ 文件夹 / [ 文件夹名 ] / 文件 / [ 文件名 ] / 评论 / [ 评论唯一标示 ]。 这样，在构造和解析 URI 的过程中， 可以帮助开发者更好的理解系统，设计程序。
条件请求与电子标签：
很多时候，数据内容可能会几个小时甚至几天都不会发生变动，这个时候根据请求时间间隔来控制缓存，就不能满足系统的需求了。通过支持条件请求与电子标签，可以帮助我们来解决这个问题。
当用户请求数据内容时，系统在返回数据的同时，在 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：
批量更新：
当用户需要更新多个资源的时候，你打算让开发者一次次的发送 HTTP 请求逐个更新吗？你可以考虑在设计 API 的时候允许客户同时创建或者更新多个资源。
REST 安全：
除了使用固有的 HTTP 基本验证，你还可以考虑通过支持表单验证，LTPA 验证，Open ID 验证等方式，来满足更多的企业安全要求。
文档服务：
是否由于 API 持续更新，使得客户端连接不同版本服务的时候疲于奔命？尝试着把你的 API 定义规范成 XML 文档，这样客户端很容易理解当前服务可以提供哪些功能，以及如何使用这些功能。
你还可以通过阅读其他文档得到更多这方面的指导，本文无法将所有的细节与技巧一一穷尽。
回页首
总结
通过以上的经验介绍和技巧举例，我们学习到了如何应用最佳实践来更好的设计 REST API。我们注意到，由于 REST API 主要针对网络应用， 并且大量调用来自于浏览器脚本，因此在细节上有很多自己独特的需要注意的技巧。此外，由于 REST 越来越成为一种系统设计的原则与构架，也要求我们的程序开发人员在设计 API 的时候需要用构架师的视角与高度来思考。希望本文能够帮助您打开 REST API 设计的思路，摸索和总结出更多的技巧，与广大开发人员分享。
?
原文地址： http://www.ibm.com/developerworks/cn/web/1103_chenyan_restapi/index.html
?