RestFul

REST： Representational State Transfer

表述（就是“资源”）性状态转移

是一组架构约束条件和原则

相关概念：

1.资源与URI

uri是web中唯一标示资源的，可看成资源地址或名称。

uri的设计技巧：

使用_或是-让其可读性更好

使用/表示资源的层级关系

使用？过滤资源

使用，或是；表示同级资源关系

2.统一资源接口

遵循统一接口原则，包含了一组受限的预定义操作，无论什么样的资源，都是通过相同的接口进行访问。

这就要求URI只应该表示资源的名称，而不应该包含资源的操作，也就是说，URI不应该用动作来描述。

如下三个就是不符合统一接口要求的Uri。

GET /getUser/1

POST /createUser

PUT /updateUser/1

下面列出了GET，DELETE，PUT和POST的典型用法:

　　GET

• 安全且幂等
• 获取表示
• 变更时获取表示（缓存）

• 200（OK） - 表示已在响应中发出

• 204（无内容） - 资源有空表示
• 301（Moved Permanently） - 资源的URI已被更新
• 303（See Other） - 其他（如，负载均衡）
• 304（not modified）- 资源未更改（缓存）
• 400 （bad request）- 指代坏请求（如，参数错误）
• 404 （not found）- 资源不存在
• 406 （not acceptable）- 服务端不支持所需表示
• 500 （internal server error）- 通用错误响应
• 503 （Service Unavailable）- 服务端当前无法处理请求

　　POST

• 不安全且不幂等
• 使用服务端管理的（自动产生）的实例号创建资源
• 创建子资源
• 部分更新资源
• 如果没有被修改，则不过更新资源（乐观锁）

• 200（OK）- 如果现有资源已被更改

• 201（created）- 如果新资源被创建
• 202（accepted）- 已接受处理请求但尚未完成（异步处理）
• 301（Moved Permanently）- 资源的URI被更新
• 303（See Other）- 其他（如，负载均衡）
• 400（bad request）- 指代坏请求
• 404 （not found）- 资源不存在
• 406 （not acceptable）- 服务端不支持所需表示
• 409 （conflict）- 通用冲突
• 412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
• 415 （unsupported media type）- 接受到的表示不受支持
• 500 （internal server error）- 通用错误响应
• 503 （Service Unavailable）- 服务当前无法处理请求

　　PUT

• 不安全但幂等
• 用客户端管理的实例号创建一个资源
• 通过替换的方式更新资源
• 如果未被修改，则更新资源（乐观锁）

• 200 （OK）- 如果已存在资源被更改

• 201 （created）- 如果新资源被创建
• 301（Moved Permanently）- 资源的URI已更改
• 303 （See Other）- 其他（如，负载均衡）
• 400 （bad request）- 指代坏请求
• 404 （not found）- 资源不存在
• 406 （not acceptable）- 服务端不支持所需表示
• 409 （conflict）- 通用冲突
• 412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
• 415 （unsupported media type）- 接受到的表示不受支持
• 500 （internal server error）- 通用错误响应
• 503 （Service Unavailable）- 服务当前无法处理请求

　　DELETE

• 不安全但幂等
• 删除资源

• 200 （OK）- 资源已被删除

• 301 （Moved Permanently）- 资源的URI已更改
• 303 （See Other）- 其他，如负载均衡
• 400 （bad request）- 指代坏请求
• 404 （not found）- 资源不存在
• 409 （conflict）- 通用冲突
• 500 （internal server error）- 通用错误响应
• 503 （Service Unavailable）- 服务端当前无法处理请求

3.资源的表述

包括数据和描述数据的元数据，例如HTTP头里的Content-Type就是一个元数据。

3.1 在URI中带上版本号 例如：

• http://api.example.com/1.0/foo
• 或是在头信息中Accept: vnd.example-com.foo+json; version=1.0

3.2 在URI使用后缀区别表述格式

.xml 或是.json等

3.3 当服务端不支持所请求的格式，应该返回一个HTTP 406响应，表示拒绝该请求。

实践：

1.使用名词而不是动词

get post put delete

/cars 返回cars集合新建 批量更新删除所有cars

/cars/1 返回id为1的car 不允许（405）更新id=1的 删除id=1

不要使用/getAllCars /createCar /deleteAllCars

2. Get方法和查询参数不涉及状态变化

不要使用GET /users/1?activate

3. 使用复数名词

用/cars而不是/car

4. 使用子资源表示关系

GET /cars/1/drivers/4 返回id=1的car中id=4的司机

5. 使用HTTP头声明序列化格式

Content-Type定义请求格式

Accept定义可接受的响应格式

6.使用HATEOAS

Hypermedia as the Engine of Application State

超媒体作为应用状态的引擎

7. 为集合提供过滤 排序 和分页

GET /cars?color=red 返回红色小车

GET /cars?sort=-manufactorer,+model 返回根据生产者降序，模型升序排序的car集合

GET /cars?fields=id,color 筛选需要的字段

GET /cars?offset=10&limit=5 分页显示，缺省limit=20和offset=0，为了将总数发给客户端，使用定制http头：X-Total-Count,link链接到上下一页

8.版本化

/blog/api/v1

9.使用Http状态码处理错误

Http状态码提供70个出错，我们只要使用10个左右：

200 – OK – 一切正常
201 – OK – 新的资源已经成功创建
204 – OK – 资源已经成功擅长

304 – Not Modified – 客户端使用缓存数据

400 – Bad Request – 请求无效，需要附加细节解释如 "JSON无效"
401 – Unauthorized – 请求需要用户验证
403 – Forbidden – 服务器已经理解了请求，但是拒绝服务或这种请求的访问是不允许的。
404 – Not found – 没有发现该资源
422 – Unprocessable Entity – 只有服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失。

500 – Internal Server Error – API开发者应该避免这种错误。

10.允许覆盖http方法

一些代理只支持POST 和 GET方法， 为了使用这些有限方法支持RESTful API，需要一种办法覆盖http原来的方法。

使用订制的HTTP头 X-HTTP-Method-Override 来覆盖POST 方法.