Restful 概述与开发规范

一 什么是Restful?

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

Restful 概述与开发规范_第1张图片

二  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":"我是返回内容"

}

            } 

你可能感兴趣的:(Restful 概述与开发规范)