REST 介绍

　　。资源Resources

　　全称Representational State Transfer (表现层状态转换)

　　表现层指的是资源（Resources）的表现层，

　　资源指的是网络上的一个实体，或者是网络上的一个具体信息，可以是一段文本，一张图片，一种服务，表示一个具体的实际资源。

　　url (统一资源定位符)， 每种资源都有一个特定的url，要想获取资源，访问它的url，因此每个url就成为了每个地址独一无二的标识符。

　　所谓的上网，就是与互联网资源的互动，url就是调用者。

　　。表象层Representational 

　　"资源" 是一种信息实体，它可以有很多的外在的表现形式,我们把资源的具体展现形式,叫做表现。

　　url 指代表资源的实体，不代表它的形式，而url它代表的是资源的位置。它的具体表现形式应该在HTTP请求头信息中用accept和content-type 字段指定，这两个字段才是对表象层的描述。

　　。状态的转换 State Transfer

　　访问一个网站，客户端和服务端会有一个交互的过程，势必涉及数据和状态的变化。

　　互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生"状态转化"（State Transfer）。而这种转化是建立在表现层之上的，所以就是"表现层状态转化"。

　　客户端用到的手段，只能是HTTP协议。具体来说，就是HTTP协议里面，四个表示操作方式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

RESTful架构　

　　（1）每一个URI代表一种资源；

　　（2）客户端和服务器之间，传递这种资源的某种表现层；

　　（3）客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。

ESTful架构设计规范　　

　　　　希望URI中不出现动词

　　　　因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分　　

• • 　　协议 API最好使用https

  • 　　域名 尽量使用专用API域名，如 api.baidu.com

  •         路径 又称为endpoint，表示API的具体资源，在restfull架构中，每个URI代表一种资源，所以URI中的名词需和实际功能对应　

HTTP 动词

• 常用动词

  GET（select） 获取资源

  POST （create）创建资源

  PUT （update）更新资源（客户端提供改变后的完整资源）

  DELETE （delete）删除资源

  PATCH（update） 更新资源（客户端提供改变的属性）

• 不常用的HTTP动词：

  HEAD 获取资源的元数据

  OPTIONS 获取信息，关于资源的那些属性是客户端可以改变的

过滤信息

如果记录的数量很多，服务器需要分段返回给用户，API应该提供参数，过滤返回结果，如下：

• ?limit=10 指定返回的记录数量
• ?offset=10 指定反馈记录的开始位置
• ?page=2&per_page=100 指定第几页，以及每页的记录数量
• ?sortby=name&order=asc 指定返回的结果按那个属性进行排序，以及如何排序
• ?animal_type_id=1 指定筛选条件

状态码

• 200 (“OK”) 用于一般性的成功返回， 不可用于请求错误返回
• 201 (“Created”) 资源被创建
• 202 (“Accepted”) 用于Controller控制类资源异步处理的返回，仅表示请求已经收到。对于耗时比较久的处理，一般用异步处理来完成
• 204 (“No Content”) 此状态可能会出现在PUT、POST、DELETE的请求中，一般表示资源存在，但消息体中不会返回任何资源相关的状态或信息。
• 301 (“Moved Permanently”) 资源的URI被转移，需要使用新的URI访问
• 302 (“Found”) 不推荐使用，此代码在HTTP1.1协议中被303/307替代。我们目前对302的使用和最初HTTP1.0定义的语意是有出入的，应该只有在GET/HEAD方法下，客户端才能根据Location执行自动跳转，而我们目前的客户端基本上是不会判断原请求方法的，无条件的执行临时重定向
• 303 (“See Other”) 返回一个资源地址URI的引用，但不强制要求客户端获取该地址的状态(访问该地址)
• 304 (“Not Modified”) 有一些类似于204状态，服务器端的资源与客户端最近访问的资源版本一致，并无修改，不返回资源消息体。可以用来降低服务端的压力
• 307 (“Temporary Redirect”) 目前URI不能提供当前请求的服务，临时性重定向到另外一个URI。在HTTP1.1中307是用来替代早期HTTP1.0中使用不当的302
• 400 (“Bad Request”) 用于客户端一般性错误返回, 在其它4xx错误以外的错误，也可以使用400，具体错误信息可以放在body中
• 401 (“Unauthorized”) 在访问一个需要验证的资源时，验证错误
• 403 (“Forbidden”) 一般用于非验证性资源访问被禁止，例如对于某些客户端只开放部分API的访问权限，而另外一些API可能无法访问时，可以给予403状态
• 404 (“Not Found”) 找不到URI对应的资源
• 405 (“Method Not Allowed”) HTTP的方法不支持，例如某些只读资源，可能不支持POST/DELETE。但405的响应header中必须声明该URI所支持的方法
• 406 (“Not Acceptable”) 客户端所请求的资源数据格式类型不被支持，例如客户端请求数据格式为application/xml，但服务器端只支持application/json
• 409 (“Conflict”) 资源状态冲突，例如客户端尝试删除一个非空的Store资源
• 412 (“Precondition Failed”) 用于有条件的操作不被满足时
• 415 (“Unsupported Media Type”) 客户所支持的数据类型，服务端无法满足
• 500 (“Internal Server Error”) 服务器端的接口错误，此错误于客户端无关

返回结果

针对不同的操作，server向用户返回的结果应该符合如下规范

• GET 返回资源对象的列表或单个资源
• POST 返回新生的资源对象
• PUT 返回完整的资源对象
• PATCH 返回完整的资源对象
• DELETE 返回空文档，并告知结果