Restful 概述与开发规范

一 什么是Restful?

          随着互联网的发展，前端设备层出不穷（手机、平板、桌面电脑、其他专用设备......），这些（客户端）设备都需要访问后端进行通信，因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信,于是RESTful诞生了，它可以通过一套统一的接口为 Web，iOS和Android提供服务

二  Restful 设计规范

1.协议

        API与用户的通信协议，总是使用https协议。

2.域名

       应该尽量将API部署在专用域名之下，例如：https://api.example.com，如果确定API很简单，不会有进一步扩展，可以考虑放在主域名：https://example.com/api

3.路径（Endpoint）

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

        在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

       举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

https://api.example.com/zoos

https://api.example.com/animals

https://api.example.com/employees

4.常用动词

GET（SELECT）：从服务器取出资源（一项或多项）。

POST（CREATE）：在服务器新建一个资源。

PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。

DELETE（DELETE）：从服务器删除资源。 

5.过滤信息（Filtering）

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

      下面是一些常见的参数。

        ?limit=10：指定返回记录的数量

        ?offset=10：指定返回记录的开始位置。

        ?page=2&per_page=100：指定第几页，以及每页的记录数。

        ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

        ?animal_type_id=1：指定筛选条件

6.宾语必须是名词

宾语就是 API 的 URL，是 HTTP 动词作用的对象。它应该是名词，不能是动词。比如，/articles这个 URL 就是正确的，而下面的 URL 不是名词，所以都是错误的。

/getAllCars

/createNewCar

/deleteAllRedCars

而应该是：

GET/cars：查询所有车辆

GET/cars/ID：查询指定的的车辆

POST/cars：创建辆车辆

DELETE/cars：删除一辆车辆

PUT/cars/ID 更新一辆车辆

7.复数URL

既然 URL 是名词，那么应该使用复数，还是单数？这没有统一的规定，但是常见的操作是读取一个集合，比如GET/cars（获取所有车辆），这里明显应该是复数。

为了统一起见，建议都使用复数 URL，比如GET/cars/2 要好于GET/car/2。

8.避免多级 URL

         比如我要查询所有某个作者文章中的某一类文章，错误的URL写法是：

        GET/authors/12/categories/2

         如果我的分级很多，这样的url往往要多看一会儿，才能懂。

         正确的做法应该是除了第一级，其他级别都用查询字符串表达：

         GET/authors/12?categories=2

9.状态码

状态码应该自定义一套让客户端看得懂的状态码，例如：

1xx：相关信息

2xx：操作成功

3xx：重定向

4xx：客户端错误

5xx：服务器错误

五大类总共包含100多种状态码，覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的（或者约定的）解释，客户端只需查看状态码，就可以判断出发生了什么情况，所以服务器应该返回尽可能精确的状态码。

10.请求／返回格式

           请求／返回格式应该为统一的JSON格式封装，并且有统一的格式

例如返回格式：

            Result {

"code":200,

"msg":"操作成功",

                 "data":{

                          "id":111,

"name":"我是返回内容"

}

            }