浅谈RESTful API设计风格

关于RESTful API

相关资料：

RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，能够使用XML格式定义或JSON格式定义。RESTFUL适用于移动互联网厂商做为业务使能接口的场景，实现第三方OTT调用移动网络资源的功能，动做类型为新增、变动、删除所调用资源。

值得注意的是REST并无一个明确的标准，而更像是一种设计的风格。

重点：RESTful是一种URL的设计风格。

解读：RESTful并无严格的语法约定，不存在“必须知足什么条件才算是RESTful”，也并非“不知足什么条件就必定不是RESTful”。一般，使用RESTful风格的API，响应给客户端的数据是XML或JSON格式的，也就是“响应正文”，是使用了先后端分离的开发方式。

在RESTful架构中，浏览器使用POST，DELETE，PUT和GET四种请求方式分别对指定的URL资源进行增删改查操做。所以，RESTful是经过URI实现对资源的管理及访问，具备扩展性强、结构清晰的特色。

解读：RESTful建议针对不一样操做，使用不一样的请求类型，例如“注册”的核心是插入用户数据，应该使用POST类型的请求方式，而“修改密码”的核心是更新数据，应该使用PUT类型的操做，等等。可是，基于开发人员的使用习惯，甚至某些复杂的业务可能包含增删改查中的多种数据操做，没法准确的定义这究竟是哪种操做，因此，常规作法依然只使用POST和GET这2种请求方式，并不使用PUT和DELETE方式。

例如：如下URL就能够视为RESTful风格的：

其实，RESTful风格有一个很是典型的特征：将核心参数直接做为URL的一部分，而不是做为参数来传递！

若是不采起RESTful风格，以上的URL可能须要设计为：

使用RESTful风格，能够使得URL更加简洁，更加易于阅读或理解！

以上示例只是csdn是这样设计的，把URL中域名以后的第1级固定为“用户名”，在details以后的固定为id值，并不表明其它网站都必须这样设计，甚至其它几乎都不是这么设计的，因此，到底怎么设计URL，取决于开发人员对URL的理解，RESTful自己并无做为相关约定！

若是没有明确的约定，能够采起如下风格：

/resources/id/command

或

/resouces/id/property/command

以上设计风格中：

• resources：资源，也就是须要访问的是哪一种数据；
• id：数据的惟一标识，若是须要访问的数据只有1条，且id须要公开，则添加；
• property：要访问的某条数据的哪一个属性；
• command：须要将某条数据或某条数据的属性执行哪一种操做。

例如，能够设计为：

/users/password/change
/addresses/10/set_default

注意：若是将某参数值放在URL中，该参数必定是具备“惟一”特性的，不然，就不该该将该参数值放在URL中。

SpringMVC框架是支持RESTful风格的！在设计请求路径时，若是请求路径中包含某个可变的参数值，使用{}框住自定义的名称便可，例如设计为：

@RequestMapping("{aid}/set_default")

在处理请求的方法的参数列表中，经过@PathVariable注解便可获取到URL中占位符对应的值：

@RequestMapping("{aid}/set_default")
public JsonResult<Void> setDefault(@PathVariable("aid") Integer aid) {
}