10 个技巧让你的 RESTful Web 服务更加实用

提示：随着RESTful Web services的流行程度不断地上升，开发人员需要知道如何避免开发中的陷阱以及让开发出来的Web service达到自己能做到的最好程度。

过去的几年里，我们看到RESTful Web services变得流行起来是有好些原因的。这里有十个技巧你应该要做的，它们能让你的RESTful Web Service更加高水准并且被其他开发人员使用起来更加简易。

1. 不要寻找一个官方的“REST 标准”



REST是一个概念，不是一个标准。因此没有任何的要求让你的 RESTful Web service在一个特定的方式下运行。话虽如此，但......

2. 还是坚持一些标准



......你的 RESTful Web services 应该遵循至少一些标准！例如用户认证的OAuth协议、数据交换的JSON和XML、网络传输和自控制的HTTP协议还有URI标准。如果你想要一个更加完整的包，开放数据协议OData是一个有效的选择（因为它够大？）。因为没有人说“REST必须坚持这些标准”这样的话，并不意味着你就应该按照自己的意愿来。

3. 确保你的文档是完美无瑕疵的



使用 SOAP 协议的WSDL（Web Service 定义语言）系统，如果你有一个基于WSDL、可以自动生成代码的工具，那么开发Web Service是相当简单的。但如果用 REST ，由于services不需要严格的定义，并且它们运行在被称为适当地正确工作的理念上。这意味着service的文档必须要非常严谨。如果你要开发一个Web Service一定要确保你的文档百分百的正确。

4. 提供 JSON 输出



JSON 已经迅速的变成web上的重要标准。首先,它很方便,因为它可以很容易地让JavaScript以最少的编码量来使用Web Service。现在有很多库可以让服务端与客户端的JSON交互工作的非常好。

5. 不要漏掉 XML



说到输出，XML 依然像往常一样非常重要。为什么要同时支持 XML 和 JSON 呢？因为并不是所有的系统都能使用 JSON 的，但如果一个系统能被称为 Web Service ，那么它就一定会被规定去处理XML。现在有成堆的遗留系统，举个例子，它是用XML工作而不是JSON。并且不是所有开发人员都想去mixing和匹配JSON跟XML的。因此要确保你的Web service系统支持这两种格式。通过HTTP请求头的“Accepts”参数来做这种支持而不是通过不同的包含参数的 service URL 来做。

6. 理解 HTTP 动词



REST Web services 其中一个很核心关键的是HTTP协议已经定义好的一大块功能。而这其中最基本的一部分就是 HTTP 动词，例如 GET、POST 。而这些基本功能在REST中已经被很好地、充分地理解，一些想法仍然不断地涌现，例如使用打补丁的方式更新实体中一些特定属性而不是整个实体。

7. 理解 URI 路由的重要性



RESTful Web services 在很大程度上是通过URI来决定干什么的。举个例子，在一次 GET 请求中，典型的URI路径会包含一个实体的主键值（或者其他标识键值）来检索获取实体的数据。例如 “http://www.example.com/service/entityname/76″ 将检索名字为 entityname， 主键值为 76 的实体。使用 REST Web services，URI 不仅是一种访问service的方式，还是控制service和作为传达你的需求的信号载体。

8. 在版本管理下进行更新维护



一件很诱人的事是你只需对唯一一个版本的service做更新维护。但真的不要这样做！确保你每一次发布更新后都新开一个分支版本来维护。最简单、最常见的办法是让你的service URI 带上版本号，通常是路径的一部分。人们最需要的一件事就是使用更新后的软件没有任何新的问题或警告出现。

9. 与你的用户保持联系



因为用户不会主动发现你的更新，因此你和你的用户保持联系就显得十分重要了。例如，当你为你的service发布一个新的版本时，你应该给每一个用户发一封邮件让他们知道，以及提供旧版本的缺陷信息。

10. 提供示例代码



对你的用户来说你要做的最好的一件事之一就是给他们提供示例代码。确保你给出的代码至少包含以下几个主要的开发语言：Java、.NET、JavaScript、Ruby还有Python。如果有必要的话，雇佣一个顾问将这些代码放在一起。因为它对于你的 service 能否被采用是绝对重要的。还要确保你的许可协议可以让你的用户没有任何风险影响地使用你的示例代码，例如可以使用 MIT 或 BSD 许可协议。