restful api规范

简介

restful是目前最流行的API设计规范，用于web数据接口设计
REST有主要两个核心精神：
一、使用resource来当作识别的资源，也就是使用一个URL网址来代表一个Resource
二、同一个Resource则可以有不通的Representations格式变化。这一章的路由实作了Resource概念，而Representation则是用了respond_to方法来实作

一、URL设计

1.1动词+宾语
restful的核心思想就是客户端发出的数据操作指令都是"动词+宾语" 比如 GET /articles 这个命令，get是动词，/atticles是宾语
动词通常就是五种HTTP方法，对应CRUD 操作
GET:读取（read）
POST:新建（create）
PUT:更新（update）
PATCH:更新（Update），通常是部分更新
DELETE:删除（Delete）
根据HTTP规范，动词一律大写

1.2动词的覆盖
有些客户端只能使用GET和POST这两种方法。服务器必须接收POST模拟其他三个方法（PUT、PATCH、DELETE）
这时，客户端发出的HTTP请求，要加上X-HTTP-Method-Override属性，告诉服务器应该使用哪一个动词，覆盖POST方法

POST /api/Person/4 HTTP/1.1 X-HTTP-Method-Override:PUT

上面代码中，X-HTTP-Method-Override指定本次请求的方法时PUT,而不是POST
1.3宾语必须时名词
宾语就是API的URL,是HTTP动词作用的对象。他应该是名词，不能是动词。比如，/articles这个URL就是正确的，而下面的URL不是名词，所以都是错误的

/getAllCars
/createNewCar
/deleteAllRedCars

上面的URL是动词，所以是错误的
1.4 复数URL
URL是名词，那么应该使用复数还是单数？
这没有统一的规则，但是常见的操作是读取一个集合，比如GET/articles（读取所有文章），这里明显是复数
为了统一起见，建议都使用复数URL,比如GET /articles/2 要好于 GET /article/2
1.5 避免多级URL
常见的情况就是，资源需要多级分类，因此容易写出多级的URL,比如获取某个作者的某一类文章

GET  /authors/12/categories

这种URL不利于扩展，语义也不明确，往往要想一会
更好的做法，除了第一级，其他级别都用查询字符串表达

GET /authors/12?categories=2

下面是另一个例子，查询已发布的文章

GET /articles/published

查询字符串的写法明显更好

GET /articles?published=true

二、状态码

2.1 状态码必须精确

客户端每一次请求，服务器都必须给出回应。回应包括HTTP状态码和数据两部分
HTTP状态码就是一个三位数，分为五个类别

lxx:相关信息
2xx：操作成功
3xx:重定向
4xx:客户端错误
5xx：服务器错误

这五大类总共包含100多种状态码，覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的解释，客户端只需查看状态码，就可以判断出发生了什么情况，所有服务器返回尽可能精确的状态码。
API不需要lxx状态码，下面介绍其他四类状态码的精确含义

2.2 2xx状态码

200状态码表示操作成功，但是不同的方法可以返回更精确的状态码

GET:200  OK
POST:  201  Created
PUT: 200  OK
PATCH:200  OK
DELETE:204  204 No  Content

上面代码中，POST返回201状态码，表示生成了新的资源；DELETE返回204状态码，表示资源已经不存在。
此外，202 Accepted 状态码表示服务器已经收到请求，但还未进行处理，通常用于异步操作。

HTTP/1.1 202  Accepted
{
   "task":{
       "href":"/api/company/job-management/jobs/2130040"
       "id":"2130040"
    }
}

2.3 3xx状态码

API用不到301状态码（永远重定向）和302状态码（暂时重定向，307也是这个含义）,因为他们可以由应用级别返回，浏览器会直接跳转，API级别可以不考虑这两种情况。
API 用到的3xx状态码，主要是303 See Other,表示参考另一个URL。它与302和307的含义一样，也是“暂时重定向”，区别在于302和307用于GET情趣，而303用于POST、PUT和DELETE请求。收到303以后，浏览器不会自动跳转，而会让用户自己决定下一步怎么办。

HTTP/1.1 303 See  Other
Location: /api/orders/12345

2.4 4xx状态码

4xx状态码表示客户端错误，主要有下面几种
400 Bad Request：服务器不理解客户端的请求，未做任何处理。
401 Unauthorized:用户未提供身份验证凭据，或者没有通过身份验证
403 Forbidden:用户通过了身份验证，但是不具有访问资源所需的权限
404 Not Forbidden:用户通过了身份验证，但是不具有访问资源所需的权限
405 Method Not Allowed:用户已经通过身份验证，但是所用的HTTP方法不在他的权限之内
410 Gone：所请求的资源已从这个地址转移，不再可用。
415 Unsupported Media Type:客户端要求的返回格式不支持。比如，API只能返回JSON格式，但是客户端要求返回XML格式
422 Unprocessable Entity:客户端上传的附件无法处理，导致请求失败
429 Too Many Requests:客户端的请求次数超过限额

2.5 5xx状态码

5xx状态码表示服务端错误。一般来说，API不会向用户透露服务器详细信息，所以只要两个状态码就够了
500 Internal Server Error：客户端请求有效，服务器处理时发生了意外
503 Service Unavailable:服务器无法处理请求，一般用于网站维护状态

三、服务器回应

3.1不要返回纯本文

API返回的数据格式，不应该是纯文本，而是一个JSON对象，因为这样才能返回标准的结构化数据。所以，服务器回应的HTTP头的Content-Type属性要设为application/json
客户端请求时，也要明确告诉服务器，可以接收JSON格式，即请求的HTTP头的ACCEPT属性也要设为application/json

GET /order/2 HTTP/1.1
Accept:application/json

3.2 返回错误时，不要返回200状态码

正确的做法是，状态码反映发生的错误 ，具体的错误信息放在数据体里面返回

HTTP/1.1  400  Bad  Request
Content-Type:application/json
{
   "error":"Invailid payoad",
   "detail":{
     "surname":"This  field  required"
  }
}

3.3提供链接

API的使用者未必知道，URL是怎么设计的，一个解决方法就是，在回应中，给出相应链接，便于下一步操作。这样的话，用户只要记住一个URL,就可以发现其他URL.这种方法叫做HATEOAS.
GitHub的API都在api.github.com这个域名。访问它，就可以得到其他URL

{
   "feed_url":"https://api.github.com/feeds",
    "follower_url":"https://api.github.com/user/followers"
    "following_url":"https://api.github.com/user/following{/target}",
    " gists_url":"https://api.github.com/gists{/gist_id}",
    "hub_url":"https://api.github.com/hub"
}

上面的回应中，挑一个URL访问，又可以得到别的URL.对于用户来说，不需要记住URL设计，只要从api.github.com一步步查找就可以了。
HATEOAS的格式没有统一规定，上面的例子中，Github将它们与其他属性放在一起。更好的做法应该是，将相关链接与其他属性分开。

HTTP/1.1 200 OK
Content-Type:application/json
{
   "status":"In  progress",
   "links:"{[
     {"rel":"cancle","method":"delete","href":"/api/status/12345"},
     {"rel":"edit","method":"put","href":"/api/status/12345"}
]}
}

四、接口规范

1.扫描任务资源为例子（资源应该使用复数形式）

"/api/scan/tasks/"     //task后端接口
"/web/scan/tasks/*"   //task界面
"/js/scan/tasks/*.js"    //task界面自定义js
"/css/scan/tasks/*.css"  //task界面自定义css
"/image/scan/tasks/*.*"  //task界面自定义图片资源
"/font/scan/tasks/*.*"   //task界面自定义字体资源

对应的API接口应该如下：

get    '/api/scan/tasks'              => "获取所有任务"
post   '/api/scan/tasks/_search'      => "检索所有任务"
post   '/api/scan/tasks'              => "创建新任务"
put    '/api/scan/tasks/:taskid'      => "修改指定ID任务"
get    '/api/scan/tasks/:taskid'      => "查看ID任务"
patch  '/api/scan/tasks/:taskid'      => "更新指定ID任务"
delete '/api/scan/tasks/:taskid'      => "删除指定ID任务"
get    '/api/scan/count/tasks'        => "根据查询条件获取任务数量"

2.批量操作 在请求头部添加 ：X -Action

post   '/api/scan/tasks'          => "批量创建新任务"
patch  '/api/scan/tasks'          => "批量更新指定任务"
delete '/api/scan/tasks'          => "批量删除指定任务"

实例：
//X-Action: bulk代表批量操作

curl -XDELETE '/api/scan/tasks' \
-H 'X-Action: bulk'
-d '
[
    "id1","id2"
]
'

#X-Action: clean 代表无条件清除
curl -XDELETE ‘/api/scan/tasks’ -H ‘X-Action: clean’

3.嵌套 (避免层级过深的URI)

put    '/api/tasks/:taskid/nodes/:nodeid'      => "修改指定ID任务的指定ID节点信息"
get    '/api/tasks/:taskid/nodes'              => "查看ID任务关联节点信息"
patch  '/api/tasks/:taskid/nodes/:nodeid'      => "更新指定ID任务关联节点信息"
delete '/api/tasks/:taskid/nodes/:nodeid'      => "删除指定ID任务关联节点信息"

4.对应界面地址规范`

get    '/html/scan/tasks/new'      => "创建新事件界面"
get    '/html/scan/tasks/:id/edit' => "编辑事件界面"
get    '/html/scan/tasks?page=1' => "事件列表界面"
get    '/html/scan/tasks/:id' => "指定事件ID界面"

5.请求body规范

一般WEB前端框架中GET/DELETE请求不会携带BODY；操作时需要切记
所有请求参数以json数据格式在请求body里面提交。实例

curl -XGET "http://127.0.0.1/api/events" \
-H 'Content-Type: application/json; charset=utf-8' \
-d '
  {
    "page_size": 1, 
    "page_num": 10
  }'

6.请求头部规范

需要在头部中添加 Content-Type: application/json; charset=utf-8`

curl -XGET "http://127.0.0.1/api/events" 
-H 'Content-Type: application/json; charset=utf-8'\
-d '{}'

7.返回状态码

200    =>  "正常请求响应"         => "一般响应"
201    =>  "创建成功请求响应"      => "异步任务"
202    =>  "接受"                => "异步任务"
204    =>  "资源不存在"           => "删除成功返回||请求资源不存在"
301    =>  "跳转"                => "界面跳转"
302    =>  "临时跳转"             => "界面跳转"
400    =>  "异常请求"             => "请求参数异常"
401    =>  "认证失败"             => "未登录操作资源"
403    =>  "禁止访问"             => "紧张访问资源"

8.返回规范

{"code":200,"message":"成功"}