RESTful API 了解

1.REST概念

REST全称是Representational State Transfer。要理解RESTful架构，需要理解Representational State Transfer这个词组到底是什么意思，它的每一个词都有些什么涵义。下面我们结合REST原则，围绕资源展开讨论，从资源的定义、获取、表述、关联、状态变迁等角度，列举一些关键概念并加以解释。

• 资源与URI
• 统一资源接口
• 资源的表述
• 资源的链接
• 状态的转移

2.RESTful API概念

在开发的过程中，我们经常会听到前后端分离这个技术名词，顾名思义，就是前台的开发和后台的开发分离开。这个技术方案的实现就是要借助API，API简单说就是开发人员提供编程接口被其他人调用，他们调用之后会返回数据供其使用。API的类型有多种，但是现在比较主流且实用的就是RESTful API。

RESTful API 的总结：
1.每一个URL代表一种资源
2.客户端和服务器之间，传递这种资源的某种表现层
3.客户端通过四个HTTP动词，对服务器端资源进行操作，实现”表现层状态转化”。具体为：
GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

2.1 RESTful API方法-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）- 服务端当前无法处理请求

  2.2 RESTful API方法-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）- 服务当前无法处理请求

2.3 RESTful API方法-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）- 服务当前无法处理请求

2.4 RESTful API方法-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.常见问题

• POST和PUT用于创建资源时有什么区别?
  POST和PUT在创建资源的区别在于，所创建的资源的名称(URI)是否由客户端决定。 例如为我的博文增加一个java的分类，生成的路径就是分类名/categories/java，那么就可以采用PUT方法。不过很多人直接把POST、GET、PUT、DELETE直接对应上CRUD，例如在一个典型的rails实现的RESTful应用中就是这么做的。

我认为，这是因为rails默认使用服务端生成的ID作为URI的缘故，而不少人就是通过rails实践REST的，所以很容易造成这种误解。

• 客户端不一定都支持这些HTTP方法吧?
  的确有这种情况，特别是一些比较古老的基于浏览器的客户端，只能支持GET和POST两种方法。

在实践上，客户端和服务端都可能需要做一些妥协。例如rails框架就支持通过隐藏参数_method=DELETE来传递真实的请求方法， 而像Backbone这样的客户端MVC框架则允许传递_method传输和设置X-HTTP-Method-Override头来规避这个问题。

• 统一接口是否意味着不能扩展带特殊语义的方法?
  统一接口并不阻止你扩展方法，只要方法对资源的操作有着具体的、可识别的语义即可，并能够保持整个接口的统一性。

像WebDAV就对HTTP方法进行了扩展，增加了LOCK、UPLOCK等方法。而github的API则支持使用PATCH方法来进行issue的更新，例如:

PATCH /repos/:owner/:repo/issues/:number
不过，需要注意的是，像PATCH这种不是HTTP标准方法的，服务端需要考虑客户端是否能够支持的问题。

• 统一资源接口对URI有什么指导意义?
  统一资源接口要求使用标准的HTTP方法对资源进行操作，所以URI只应该来表示资源的名称，而不应该包括资源的操作。

通俗来说，URI不应该使用动作来描述。例如，下面是一些不符合统一接口要求的URI:

GET /getUser/1
POST /createUser
PUT /updateUser/1
DELETE /deleteUser/1

4.RESTful API 应用

• Django Rest framework

1.建立 Models
2.依靠 Serialiers 将数据库取出的数据 Parse 为 API 的数据（可用于返回给客户端，也可用于浏览器显示）
3.ViewSet 是一个 views 的集合，根据客户端的请求（GET、POST等），返回 Serialiers 处理的数据，权限 Premissions 也在这一步做处理
4.ViewSet 可在 Routers 进行注册，注册后会显示在 Api Root 页上
5.在 urls 里注册 ViewSet 生成的 view，指定监听的 url