RESTful APIs

1 介绍

说RESTful之前，先说说其它的问题。

1.1 网站定位？

CS软件，我们称之为软件，不涉及到RPC时，对数据和业务都是用面向对象的方式处理，那么网站算不算软件？

1.2 面向对象？

Java语言本身是面向对象的，经过Hibernate、Mybatis等ORM框架，数据操作也是面向对象的，还有什么没有被OO？
不觉得http://ip:host/deleteUserByCidAndName?cid=xx&name=yy 这样的路径奇怪？

1.3 Webserice？

核心：WDSL、UDDI、SOAP，数据格式为XML，经由HTTP再封装一次，调用方法风格为RPC格式。有什么问题?
Webservice太重量级，而且RPC请求方式如getUserByIdAndName，是平行格式，即各个请求之间是没有逻辑上的关系的，请求不友好，不易控制……

1.4 HTTP 的形式

我为什么不用更轻量的HTTP的服务APIs,如（快递）

    URL url = new URL("http://www.xxx.cn/rest/?"
                    + "&order=" + expressDetail.getEno() ;
            //连接
            HttpURLConnection con = (HttpURLConnection) url.openConnection(); 
            con.setAllowUserInteraction(false);
            con.setRequestMethod("GET");
            con.setRequestProperty("Charset", "UTF-8");
            InputStream urlStream = url.openStream();

使用以上几行代码,即可完成一次请求交互,我为什么还要使用沉重的传统的WebService?

1.5 继续优化

既然使用HTTP方式的WebService,为什么不让它有一种更好的风格?

2 概念

2.1 REST

Representational State Transfer, 表述性状态传递，直白的翻译我是没理解，就像HTTP翻译成超文本传输协议，一样容易误解（传输协议不应该是传输层？英文思维学编程的优势，参见印度）。
另外REST是推荐的APIs风格，不是标准。符合REST风格的，称为RESTful。

2.2 特点

这是一种
{
轻量级
面向对象
易于控制（权限）
符合HTTP协议
Webservice升级版
}
的风格。

2.3 三个重点

路径 URI
方法 method
内容格式 type

2.4 四个阶段

源自三个重点:

分别为:

1. 摆脱POX(Plain Old XML),我的理解是传统的WSDL\SOAP的webservice
2. 如何定义资源
3. 如何使用HTTP的方法
4. 如何控制超媒体(img\video等)

3 如何RESTful

3.1 路径

面向对象是一种以人的视角看待世界的方式，所谓人的视角我认为就是分类、分层，如xx是yy的(继承)。而REST就是将网站看做是有层次的资源，达到面向对象的目的，如 http://host:port/projects/14/comments

3.2 方法

八种方法（虽然GET、POST被使用的更多），包含了网站开发需要的 增删改查、上传操作。

3.3 内容格式

Json
Xml
Image
……

3.4 最终样式

http://host:port/projects/14/comments GET
http://host:port/projects/14/comments/1  DELETE
http://host:port/projects/14/comments POST

即comment 是 project 的；删除id为14的project下ID为1的评论……

3.5 其它建议

better URI

4 SpringMVC

4.1 主要注解

@RequestMapping
@PathVariable
@ResponseBody
@RequestParam
@MatrixVariable（3.2）

4.2 路径

主要靠@RequestMapping解决,通过/区分资源的层次。

4.3 方法

主要靠@RequestMapping下的Method注解,其支持:

4.4 格式

@RequestMapping下，consumes为处理的格式限制,produces为返回的数据格式:

或者

5 项目使用

网站前端使用较多，尤其是需要为IOS等其他设备提供服务时。
网站管理端因为后台管理端很少开发公共API,用的也比较少，但是可以用REST优化一下路径，让API（Web Service）风格更好,方便开发和测试理解，也容易进行权限控制，如：
http://ip:host/project/index.htm
http://ip:host/project/update.htm
http://ip:host/project/add.htm
http://ip:host/project/delete.htm

6 其它

其它需要考虑的内容:
API版本
服务器对方法的支持
Spring HATEOAS
SOA
ESB