restful url 设计规范_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":"我是返回内容"

}

}