内容来源：
http://www.ruanyifeng.com/blog/2011/09/restful.html
http://www.ruanyifeng.com/blog/2014/05/restful_api.html

理解RESTful 架构

REST 即 Representational State Transfer 的缩写，一般翻译为“表现层状态转化”。
如果一个架构符合REST原则，就可以称之为TESTful架构

资源（Resources）

REST 缺少了一个主语，“表现层”实际指的是“资源（Resources）”的表现层
“资源”指代网络上的一个具体信息，可以是一段文本、图片、歌曲，或者一种服务。
可以用URI（统一资源定位符）指向“资源”，每种资源对应一个特定的URI。

表现层（Representation）

“资源”是一种信息实体，它可以又多种外在表现形式。“资源”具体呈现出来的形式，叫做“表现层”
比如：文本的表现形式可以为txt格式，也可以用HTML、XML、JSON、二进制 格式；图片可以用JPG、PNG表现。

URL只代表资源的实体，不代表形式。比如有的网址最后的“.html”后缀名是不必要的，因为这个后缀名表示格式，属于“表现层”，URI只应该只代表资源的位置。它的具体表现形式，应该在HTTP请求的头信息中用Accept 和 Content-Type 字段指定，这两个字段才是对“表现层”的描述。

状态转化

访问一个网站，就代表了客户端和服务器的一个互动过程。在这个过程中，就涉及到了数据和状态的变化。
互联网通信协议HTTP协议，是一个无状态协议。即意味着，所有的转改都保存在服务器端。因此，客户端想要操作服务器，必须通过某种手段，让服务器端发生“状态转化”。这种转化是建立在表现层之上的，所以就是：“表现层状态转化”。

客户端与服务器互动用到手段是HTTP协议，具体讲就是HTTP协议里面的四个表示操作方式的动词：GET、POST、PUT、DELETE。 分别代表了四种操作：GET 获取资源，POST 新建资源（也可以用来更新资源）, PUT用来更新资源，DELETE用来删除资源。

RESTful架构综述

1）每一个URI代表一种资源
2）客户端和服务器之间，传递这种资源的某种表现层
3）客户端通过四个HTTP动词，对服务器资源进行操作，实现“表现层状态转化”

常见误区

1） URI 包含动词：“资源”表示一种实体，所以应该是名词，URI不应该有动词，动词应该放在HTTP协议中。
举例： 某个URI是 /posts/show/1 ，其中show是动词，URI就设计的有问题。正确的写法应该是/posts/1 然后用GET方法表示show。
2） HTTP动词无法表示的某些动作，比如网上汇款，从账户1向账户2汇款500元
错误的URI是： POST /accounts/1/transfer/500/to/2
正确的做法是把动词transfer 改成名词 transaction，资源不能是动词，可以把这种情况作为一种服务：
POST /transaction HTTP/1.1
Hpst：127.0.0.1

from=1&to=2&amout=500.00

3) 在URI中加入版本号

http://www.example.com/app/v1.0/foo http://www.example.com/app/v1.1/foo http://www.example.com/app/v2.0/foo

不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分 https://www.informit.com/articles/article.aspx?p=1566460

Accept: vnd.example-com.foo+json; version=1.0 Accept: vnd.example-com.foo+json; version=1.1 Accept: vnd.example-com.foo+json; version=2.0

RESTful API 设计细节

协议

HTTPS 协议

域名

尽量将API部署在专用域名之下
https://api.example.com
如果API不会有进一步扩展，可以放在主域名下
https://example.com/api

版本

1） API版本号放在URI
https://api.example.com/v1
2) 版本号放在http头信息中，不如放URL直观。（可能具体到开发也没有在URL中方便）
　Accept: api.example.com.foo+json; version=1.0

路径

路径又称“终点（endpoint）”，表示API的具体网址。

RESTful 架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词，而且所有的名词往往与数据库的表名对应。

一般来说，数据库中的表都是同种记录的“集合（collection）”,所以API中的名词也应该使用复数
比如有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则他们的路径应该设计成下面这样：
https://api.example.com/v1/zoos
https``:``//api.example.com/v1/animals
https://api.example.com/v1/employees

HTTP动词

常用的HTTP动词有下面五个（括号里对应的SQL命令）：

  • GET（SELECT）:从服务器取出资源（一项或者多项）
  • POST （CREATE）： 在服务器新建一个资源
  • PUT （UPDATE）：在服务器更新资源 （客户端提供改变后的完整资源）
  • PATCH （UPDATE）: 在在更新资源 （客户端提供改变的属性）
  • DELETE （DELETE）: 在服务器删除资源

两个不常用的HTTP动词：

  • HEAD：获取资源的元数据
  • OPTIONS： 获取信息，关于资源的哪些属性是客户端可以改变的

例子：

  • GET /zoos：列出所有动物园
  • POST /zoos：新建一个动物园
  • GET /zoos/ID：获取某个指定动物园的信息
  • PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
  • PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
  • DELETE /zoos/ID：删除某个动物园
  • GET /zoos/ID/animals：列出某个指定动物园的所有动物
  • DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

过滤信息

常见的参数

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

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

状态码

常见的状态码以及对应的HTTP动词

  • 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
  • 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
  • 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
  • 204 NO CONTENT - [DELETE]：用户删除数据成功。
  • 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
  • 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
  • 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
  • 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
  • 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
  • 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
  • 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
  • 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

完整列表 https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

错误处理

返回的错误信息中将 error作为键名，出错信息作为键值即可
{
error:”Invalid API key”
}

返回结果

针对不同的操作，服务器向用户返回的结果应该符合以下规范。

  • GET /collection：返回资源对象的列表（数组）
  • GET /collection/resource：返回单个资源对象
  • POST /collection：返回新生成的资源对象
  • PUT /collection/resource：返回完整的资源对象
  • PATCH /collection/resource：返回完整的资源对象
  • DELETE /collection/resource：返回一个空文档

Hypermedia API（超媒体API）

即放回的结果中提供链接，连向其他API方法，是用户不查看文档，也知道下一步应该做什么。
比如，当用户向api.example.com 的根目录发出请求，得到这样一个文档

{“link”: {
“rel”: “collection https://www.example.com/zoos”,
“href”: “https://api.example.com/zoos“,
“title”: “List of zoos”,
“type”: “application/vnd.yourformat+json”
}}

link 表示下一步该调用什么API。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型

Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。

其他

1） API 身份认证使用 OAuth 2.0 框架
2） 服务器返回的数据格式，应该尽量使用JSON，避免使用XML