如何设计好的RESTful API 之好的RESTful API 特征

导读：设计好RESTful API对于软件架构的可扩展性、可伸缩性和消费者的体验都具有至关重要的作用。本次虚拟研讨会的主题是，如何设计好的RESTful API。

关键词：RESTful API REST OAuth协议 

REST架构风格最初由Roy T. Fielding（HTTP/1.1协议专家组负责人）在其2000年的博士学位论文中提出。HTTP就是该架构风格的一个典型应用。从其诞生之日开始，它就因其可扩展性和简单性受到越来越多的架构师和开发者们的青睐。它必将得到更大的发展。一方面，随着云计算和移动计算的兴起，许多企业愿意在互联网上共享自己的数据、功能；另一方面，在企业中，RESTful API（也称RESTful Web服务）也逐渐超越SOAP成为实现SOA的重要手段之一。为此，InfoQ将通过一系列深度文章和虚拟研讨的形式，深入剖析REST，以飨读者。

设计好RESTful API对于软件架构的可扩展性、可伸缩性和消费者的体验都具有至关重要的作用。本次虚拟研讨会的主题是，如何设计好的RESTful API。我们邀请了几位国内对REST风格架构及RESTful API设计颇有心得的专家，请他们就自己的实战经验谈谈对这一问题的看法。他们分别是李锟、李建业、丁雪丰、马钧。

问题

我们为本次虚拟研讨会设计的问题有：

1. 什么是好的RESTful API？相信每个人都有自己的评判标准。那么，您认为一个好的RESTful API应该具有哪些特征呢？
2. 安全是恒久的话题，对于基于WSDL和SOAP的Web Service，我们有WS-Security这样的安全规范来指导实现认证、授权、身份管理等安全需求。那么，RESTful API有无成熟可用规范或实现框架呢？如何保证RESTful API的安全性呢？
3. 如何对RESTful API进行版本控制，请分享您认为实用的做法？
4. HTTP1.1规范中给出的动词对于设计RESTful API够用吗？您在实际项目中会扩展自己的动词吗？在什么情况下需要扩展？
5. 今年5月份发布的JAX-RS 2.0规范对于RSTfulAPI的设计最有价值的特性是哪个（些）？ 它（们）用于解决什么问题？
6. 能否为InfoQ的读者们推荐一款实用的RESTful API开发框架，并说明您的推介理由
7. HTTP2.0规范正在制定当中，您对它的期待是什么？

InfoQ：什么是好的RESTful API？相信每个人都有自己的评判标准。那么，您认为一个好的RESTful API应该具有哪些特征呢？
 

李锟：一个好的RESTful API，应该具备以下特征： 这个API应该是对浏览器友好的，能够很好地融入Web，而不是与Web格格不入。 1.浏览器是最常见和最通用的REST客户端。好的RESTful API应该能够使用浏览器+HTML完成所有的测试（不需要使用编程语言）。这样的API还可以很方便地使用各种自动化的Web功能测试、性能测试工具来做测试。Web前端应用（基于浏览器的RIA应用、移动App等等）也可以很方便地将多个RESTful API的功能组合起来，建造Mashup类的应用。 这个API中所包含的资源和对于资源的操作，应该是直观和容易理解的，并且符合HTTP协议的要求。 REST开发又被称作“面向资源的开发”，这说明对于资源的抽象，是设计RESTful API的核心内容。RESTful API建模的过程与面向对象建模类似，是以名词为核心的。这些名词就是资源，任何可命名的抽象概念都可以定义为一个资源。而HTTP协议并不是一种传输协议，它实际提供了一个操作资源的统一接口。对于资源的任何操作，都应该映射到HTTP的几个有限的方法（常用的有GET/POST/PUT/DELETE四个方法，还有不常用的PATCH/HEAD/OPTIONS方法）上面。所以RESTful API建模的过程，可以看作是具有统一接口约束的面向对象建模过程。 按照HTTP协议的规定，GET方法是安全且幂等的，POST方法是既不安全也不幂等的（可以用来作为所有写操作的通配方法），PUT、DELETE方法都是不安全但幂等的。将对资源的操作合理映射到这四个方法上面，既不过度使用某个方法（例如过度使用GET方法或POST方法），也不添加过多的操作以至于HTTP的四个方法不够用。 2.如果发现资源上的操作过多，以至于HTTP的方法不够用，应该考虑设计出更多的资源。设计出更多资源（以及相应的URI）对于RESTful API来说并没有什么害处。 这个API应该是松耦合的。 RESTful API的设计包括了三个循序渐进、由低到高的层次：资源抽象、统一接口、超文本驱动。正是这三个层次确保了RESTful API的松耦合性。 3.当设计面向互联网的API时，松耦合变成了一种“必须有”的强需求。紧耦合的API非常脆弱，一旦公布出去，服务器端和客户端都无法持续进化。尤其是服务器端，公布出去的接口根本不敢改，改了之后，几乎所有客户端应用立即无法正常工作。REST这种架构风格就是紧耦合API的解毒剂，这个话题可以谈的很深，这里就不展开了。感兴趣的读者可以参考《REST实战》。 这个API中所使用的表述格式应该是常见的通用格式 在RESTful API中，对于资源的操作，是通过在服务器端-客户端之间传递资源的表述来间接完成的。资源的表述可以有很多种格式，并且在响应和请求中的资源表述格式也会有所不同。GET/POST响应中的资源表述格式，常见的有HTML、XML、JSON；POST/PUT请求中的资源表述格式，常见的有标准的HTML表单参数、XML、JSON。 4.这些常见表述格式，处理起来非常容易，有大量的框架和库提供支持。所以除非有很合理的要求，通常不需要使用自定义的私有格式。 使用HTTP响应状态代码来表达各种出错情况 HTTP响应状态代码，是HTTP协议这个统一接口中用来表达出错情况的标准机制。响应状态代码分成两部分：status code和reason phase。两部分都是可定制的，也可以使用标准的status code，只定制reason phase。 5.如果一个所谓的“RESTful API”对于任何请求都返回200 OK响应，在响应的消息体中返回出错情况信息，这种做法显然不符合“确保操作语义的可见性”这个REST架构风格的基本要求。 这个API应该对于HTTP缓存是友好的 6.充分利用好HTTP缓存是RESTful API可伸缩性的根本。HTTP协议是一个分层的架构，从两端的user agent到origin server之间，可以插入很多中间组件。而在整个HTTP通信链条的很多位置，都可以设置缓存。HTTP协议内建有很好的缓存机制，可以分成过期模型和验证模型两套缓存机制。如果API设计者完全没有考虑过如何利用HTTP缓存，那么这个API的可伸缩性会有很多问题。

李建业：首先说明一下，对REST这个概念，我一般把它理解为REST风格的架构，但是现在实践中最为广泛认知的是HTTP，而它是REST的一个实现，所以RESTful API也可以不太严格的指基于HTTP的API——当然，即使是不严格的时候，API本身也应该力求遵循REST架构风格。 我认为，一个RESTful API最重要的一点应该是——“尽可能少的先验信息”，这一条也同时是我判断一个好的RESTful API的标准。 比如HTTP动词，在实践中，大家可能会常常纠结于有效利用 HTTP 动词，但这却并不是特别重要的事情——除非你理解这么做的价值。HTTP 动词最重要的地方在于它是标准阐明了的行为，也就是说，如果我们的“客户端”遵循约定，那么就不必要发明新的动词，也就不必增加“先验信息”；但是，所谓“先验信息”，针对的是客户端——对API来说就是调用者，对于一些企业内部系统，或者一些传统系统，由于“资源”很稳定，对资源的操作也很稳定，这些系统的“调用客户端”不是浏览器而是另一个系统，此时如果强制对应到HTTP动词，反而会变成额外的“先验信息”，这时我就不会太拘泥HTTP动词，自己制定一套动词放在参数中也可以接受——只要动词不变化，这个系统依然是REST风格的。 再比如Response里面的Content-Type，这个有时会被新手忽略，但这其实很重要，因为一般涉及到系统间协同的API，往往不会使用普通的文本，比较常见的是使用json表达复杂结构，而这与通常的缺省理解不同（缺省一般会认为是text/plain和text/html），所以如果在API中忘记用Content-Type进行区分的话，后续对多种类型的客户端接入的支持就会变成陷阱（我们多次遇到过这个问题）。而如果一开始就检查是否增加先验知识（缺省Content-Type为plain或者允许指定Content-Type），那这一困难就可以避免了。

丁雪丰：首先，应该正确地使用HTTP的统一接口，比如HTTP的动词，如果不分青红皂白清一色POST那显然还有改进的余地； 其次，资源有合适的粒度，可以从三个方面来评判资源的粒度是否合理——网络的效率、表述的大小以及客户端使用时的易用程度； 最后，是表述的设计，除了表述的正文内容，还有其中的URI和链接，这些都是评判一个RESTful API好坏的标准。

马钧：在我看来，一个好的API标准，就是能尽量利用到HTTP协议的特性，将HTTP当成一种转移协议，而不是传输协议。包括但不限于：利用HTTP的各种动词来明确操作；包含有内容协商，可以根据请求头提供的参数选择一个资源最合适的媒体类型、语言、字符集和编码的表现；使用不同的返回代码来描述各种状态。但实际上见到过的很多声称RESTful API，包括国内的和国外的，能符合这些条件的并不多。parse.com提供的API是我见到过的较为不错的RESTful API，可以作为范例参考。