转自：http://blog.csdn.net/yue7603835/article/details/52536497
URI
URI （Uniform Resource Identifier，统一资源标识符)，资源一般对应服务器端领域模型中的实体类。
URI规范
- 不用大写;
- 用中杠-不用下杠_;
- 参数列表要encode;
- URI中的名词表示资源集合，使用复数形式。
资源集合 vs 单个资源
URI表示资源的两种方式：资源集合、单个资源。
- 资源集合：
/zoos //所有动物园
/zoos/1/animals //id为1的动物园中的所有动物
- 单个资源：
/zoos/1 //id为1的动物园
/zoos/1;2;3 //id为1，2，3的动物园
避免层级过深的URI
/在uri中表达层级，用于按实体关联关系进行对象导航，一般根据id导航。
过深的导航容易导致uri膨胀，不易维护，如:
GET /zoos/1/areas/3/animals/4。
尽量使用查询参数代替路径中的实体导航，如:
GET /animals?zoo=1&area=3；
对Composite资源的访问
服务器端的组合实体必须在uri中通过父实体的id导航访问。
组合实体不是first-class的实体，它的生命周期完全依赖父实体，它是无法独立存在的，在实现上通常是对数据库表中某些列的抽象，不直接对应表，也无id。一个常见的例子是 User — Address，Address是对User表中zipCode，country，city三个字段的简单抽象，无法独立于User存在。必须通过User索引到Address：
GET /user/1/addresses //id为1的用户的地址
Request
HTTP方法
通过标准HTTP方法对资源CRUD：
GET：查询
GET /zoos //查询所有动物园
GET /zoos/1 //查询id为1的动物园
GET /zoos/1/employees //查询id为1的动物园的所有员工
GET /zoos/1/employees/1 //查询id为1的动物园的1号员工
POST：创建单个资源。POST一般向“资源集合”型uri发起
POST /animals //新增动物
POST /zoos/1/employees //为id为1的动物园雇佣员工
PUT：更新单个资源（全量），客户端提供完整的更新后的资源。与之对应的是 PATCH，PATCH 负责部分更新，客户端提供要更新的那些字段。PUT/PATCH一般向“单个资源”型uri发起
PUT /animals/1
PUT /zoos/1
DELETE：删除
DELETE /zoos/1/employees/2 //删除id为1的动物园的2号员工
DELETE /zoos/1/employees/2;4;5 //删除id为1的动物园的2,4,5号员工
DELETE /zoos/1/animals //删除id为1的动物园内的所有动物
安全性和幂等性
安全性：不会改变资源状态，可以理解为只读的；
幂等性：执行1次和执行N次，对资源状态改变的效果是等价的。
| 安全性 | 幂等性 | |
|---|---|---|
| get | √ | √ |
| post | × | × |
| put | × | √ |
| delete | × | √ |
安全性和幂等性均不保证反复请求能拿到相同的response。以 DELETE 为例，第一次DELETE返回200表示删除成功，第二次返回404提示资源不存在，这是允许的。
复杂查询
查询可以捎带以下参数：
| 实例 | 备注 | |
|---|---|---|
| 过滤条件 | ?type=1&age=16 | 允许一定的uri冗余，如/zoos/1与/zoos?id=1 |
| 排序 | ?sort=age,desc | |
| 投影 | ?whitelist=id,name,email | |
| 分页 | ?limit=10&offset=3 |
Format
只用以下常见的3种body format：
- Content-Type: application/json；spring mvc用@RequestBody解析成对象
POST /v1/animal HTTP/1.1
Host: api.example.org
Accept: application/json
Content-Type: application/json
Content-Length: 24
{
"name": "Gir",
"animalType": "12"
}
- Content-Type: application/x-www-form-urlencoded (浏览器POST表单用的格式，@RequestBody不能解析)
POST /login HTTP/1.1
Host: example.com
Content-Length: 31
Accept: text/html
Content-Type: application/x-www-form-urlencoded
username=root&password=Zion0101
- multipart/form-data; boundary=----WebKitFormBoundaryITio08aDVqufJd9L(表单有文件上传时的格式)
Content Negotiation
资源可以有多种表示方式，如json、xml、pdf、excel等等，客户端可以指定自己期望的格式，通常有两种方式：
- http header Accept：
Accept:application/xml;q=0.6,application/atom+xml;q=1.0 - uri中加文件后缀
/zoo/1.json
Response
- 不要包装：
response 的 body 直接就是数据，不要做多余的包装。错误示例：
{
"success":true,
"data":{"id":1,"name":"xiaotuan"},
}
正确示例:
{
"id":1,
"name":"xiaotuan"
}
- 各HTTP方法成功处理后的数据格式
| response 格式 | |
|---|---|
| GET | 单个对象、集合 |
| POST | 新增成功的对象 |
| PUT/PATCH | 更新成功的对象 |
| DELETE | 空 |
