1、Restful接口规范

一、Web开发模式和API接口

Web开发有两种模式
1.前后端混合开发模式
2.前后端分离

那我们之前一直都是前后端混合开发，但实际工作中的后端开发，只需要专注的写后端就可以了，涉及到前端的地方只需要提供对应的接口就可以了。

大家都说后端开发就是不停的写接口，那么到底什么是接口呢？

api接口：前后台信息交互的媒介
类似于这种：https://api.weibo.com/2/statuses/show.json

二、Restful规范

RESTful是一种定义API接口的设计风格，尤其适用于前后端分离的应用模式中

1、协议

为保证数据安全，API与用户的通信协议，通常使用https进行交互

2、域名

接口应带有api关键字表。如下

https://api.baidu.com
https://127.0.0.1/api/books

3、多数据版本共存

应该将API的版本号放入URL。如下

https://api.baidu.com/v1
https://api.baidu.com/v2

4、路径

数据即是资源，均使用名词（可复数）

https://api.baidu.com/v1/books
https://api.baidu.com/users

# 地址中不带操作资源的动词，例如：https://api.baidu.com/delete-user

5、资源操作由请求方式决定

操作资源一般都会涉及到增删改查，我们提供请求方式来标识增删改查动作

https://api.baidu.com/books  # get请求：获取所有书
https://api.baidu.com/books/1  # get请求：获取主键为1的书
https://api.baidu.com/books  # post请求：新增一本书书
https://api.baidu.com/books/1  # put请求：整体修改主键为1的书
https://api.baidu.com/books/1  # patch请求：局部修改主键为1的书
https://api.baidu.com/books/1  # delete请求：删除主键为1的书

6、过滤信息

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

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

# 示例
https://api.example.com/v1/zoos?limit=10  # 指定返回记录的数量

7、响应中带状态码

常用的状态码如下

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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

8、返回错误信息

与第七条一起使用，比如说状态码是401，应该返回如下内容

{
    error: "无权限操作"
}

9、返回结果

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

GET /books：返回资源对象的列表（数组）
GET /books/1：返回单个资源对象
POST /books：返回新生成的资源对象
PUT /books/2：返回完整的资源对象 (完全修改)
PATCH /books/2：返回完整的资源对象（局部修改）
DELETE /books/1：返回一个空文档

10、响应中带链接

# Hypermedia API，RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么
{
  	"status": 0,
  	"msg": "ok",
  	"results":[
        {
            "name":"肯德基(罗餐厅)",
            "img": "https://image.baidu.com/kfc/001.png"
        }
      	...
		]
}

三、序列化

# 序列化是一种数据转换格式
序列化： 把我们识别的数据转换成指定的格式提供给别人，比如把Python的字典序列化成json格式
反序列化：把别人提供的数据转换/还原成我们需要的格式。比如把json格式数据反序列成Python的字典