这是我参与11月更文挑战的第9天，活动详情查看：2021最后一次更文挑战

前言

web开发模式有两种，分别是前后端不分离和前后端分离两种模式，前后端不分离的模式下需要自己写HTML模板文件，而前后端分离的模式下后端只专注于后端接口，返回给前端json或者xml格式的数据，在实际项目开发中，前后端分离的模式用的较多，使用前后端分离的模式进行开发时就需要规范API接口以及接口规范。本文来介绍一下吧~

API接口

API接口是指通过网络对前后台信息交互规则的url链接，就是前后端交流的媒介，双方协议好传输数据的格式。但是webAPI接口与一般的url链接还是有区别的，webAPI接口简单概括有一下有以下四个特点：

url：长得像返回数据的url链接：https://api.map.baidu.com/place/v2/search
请求方式：get、post、put、patch、delete
请求参数：json或xml格式的key-value类型数据
响应结果：json或xml格式的数据

Restful规范

REST全称是Representational State Transfer，中文意思是表述（编者注：通常译为表征性状态转移）。RESTful是一种定义Web API接口的设计风格，尤其适用于前后端分离的应用模式中。这种风格的理念认为后端开发任务就是提供数据的，对外提供的是数据资源的访问接口。所以在定义接口时，客户端访问的URL路径就表示这种要操作的数据资源。事实上，我们可以使用任何一个框架都可以实现符合restful规范的API接口。

restful规范大概有下述几条：

数据的安全保障：url链接一般都采用https协议进行传输，采用https协议，可以提高数据交互过程中的安全性
接口特征表现，看到api字眼，就代表该请求url链接是完成前后台数据交互的：

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

多版本共存，在url链接中标识数据版本，url链接中的v1、v2就是不同数据版本的体现（只有在一种数据资源有多版本情况下）

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

数据即是资源，接口url中均使用名词，接口一般都是完成前后台数据的交互，交互的数据我们称之为资源，一般提倡用资源的复数形式，在url链接中尽量不要出现操作资源的动词，但是特殊的接口可以出现动词，因为这些接口一般没有一个明确的资源，或是动词就是接口的核心含义。

# 正常接口
- https://api.baidu.com/users
- https://api.baidu.com/books
- https://api.baidu.com/book
 
 # 错误示范
 - https://api.baidu.com/delete-user
 
 # 动词示范
 - https://api.baidu.com/place/search
 - https://api.baidu.com/login

资源操作由请求方式决定（method），操作资源一般都会涉及到增删改查，提供请求方式来标识增删改查动作

- 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的书

过滤，通过在url上传参的形式传递搜索条件

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

响应状态码，不同的状态码代表不同的响应状态
错误处理：应该返回错误信息error当作错误信息的key

{ error: "无权限操作"}

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

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

需要url请求的资源需要访问资源的请求链接

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

结语

文章首发于微信公众号程序媛小庄，同步于掘金。

码字不易，转载请说明出处，走过路过的小伙伴们伸出可爱的小指头点个赞再走吧(╹▽╹)

API与restful规范

前言

API接口

Restful规范

结语