RESTful笔记及规范

发表于

前言：REST是一种风格参考，不是硬性要求。

Roy Fielding的毕业论文。这哥们参与设计HTTP协议，也是Apache Web的co-founde；所以提出的设计思想是有保障的。

论文地址：https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

一：所解决的问题：

我认为目前RESTful风格所解决的问题是:

cmd-markdown-logo

clients:

  • IOS
  • Android
  • web
  • Other

RESTful还未形成的时候或许不同的设备需要提供不同的API，那在RESTful出现之后可以标准化整个API，在标准化的过程中肯定需要适配多个client，不同的client需要的数据结构或者数据不同但是大同小异，所以在实现API的过程中提高健壮性、可靠性、通用性、完整性是必然

二：传统RPC或Struts的实际效果来总结RESTful的特点：

  • 1.基础操作符 GET POST DEL PUT
  • 2.HTTP中的Headers的利用率
  • 3.URI的命名
  • 4.解除JSP方式，前后分离
  • 5.分离后的交互数据结构
  • 6.URI是名词不是动词，推荐复数
  • 7.安全的URI

以上几点就能看出，满足这几个特点基本可以对HTTP的请求形成一套标准化

三：实际定义

1. 暂定admin为标准restful 包含增删改查

1
2
3
4
5
GET /api/admin/v1/employees          //获取集合，自动分页
GET  /api/admin/v1/employee/{id}    //一个对象
DELETE /api/admin/v1/employee/{id}  //删除
POST /api/admin/v1/employee         //保存
PUT /api/admin/v1/employee/{id}     //修改

注意POST方法保存的时候，服务端MVC技巧：

Request中Headers使用：Content-Type:application/x-www-form-urlencoded
使用该header可以直接在Controller中使用Entity作为入参，请求发起时使用Entity字段作为Body，这样传入Contorller会自动填充Entity，避免RequestParam需要写大量的key-value

2. 暂定One To Mony 格式

1
2
GET /api/v1/order/{id}/products
GET /api/v1/order/{id}/product/{id}

3. 暂定response

RESTful推荐JSON或XML作为response

除去HTTP的Request.code （如：4XX,5XX）等;

以下格式作为交互格式:

例1：

1
2
3
4
5
{
	"code":1,  //作为controller的response标记
	"msg":"成功", //具体服务端消息
	"param":"" //如果结果为成功或其他定义，提供data
}

例2：

1
2
3
4
5
6
7
8
9
{
	"code":1,
	"msg":"成功"
	"param":
		{
			"name":"李",
			"address":"BeiJing"
		}
}

####未完待续

基于本篇推荐书籍

《Java RESTful Web Service 实战(第二版)》