api接口url化

Posted 2023-04-18

参考技术A 目录
为接口提供一个主页
为序列化类增加url

配置全局分页

为每个url都增加一个参数name。

在myapp下新建一个api_path.py
在myapp/api_path.py增加主页的view

完成这个功能只需要一个简单的FBV提供GET方法即可，这个view将返回所有有效的url（通过JSON格式）。
reverse方法通过url的名字，返回一个完整的url。
在myapp/api_path.py配置主页的url
尽量不要使用任何正则式，保证我们直接访问最原始的url就可以访问的接口的主页。
养成好习惯，为每个url都增加参数name。

配置后的接口主页

现在可以直接通过点击链接访问有效的url了，但是不要忘记当我们增加新的url后，要在主页的view中进行配置。

在snippet/serializers.py更改序列化类

将ModelSerializer改为HyperlinkedModelSerializer。
在继承后，就自动会增加一个字段url，但是需要手动配置到fields中
为普通字段提供了HyperlinkedIdentityField，为外键字段提供了HyperlinkedRelatedField。其中最关键的参数view_name的值是url的参数name，也就是通过url配置中的name来获取到对应的url。

Web API接口

Web API接口

接口概念：

通过网络，规定了前后台信息交互规则的url链接，也就是前后台信息交互的媒介

接口组成：

url链接 - 长得像返回数据的url链接

请求方式 - get(查)、post(增)、put(整体改)、patch(局部改)、delete(删)

请求参数 - 拼接参数、数据包参数(urlencoded、form-data、json)

响应结果 - 响应的json数据

接口测试工具：Postman

Postman是一款接口调试工具，是一款免费的可视化软件，同时支持各种操作系统平台，是测试接口的首选工具。
Postman可以直接从官网：https://www.getpostman.com/downloads/下载获得，然后进行傻瓜式安装

• 工作面板

•  简易的get请求

•  案例：请求百度地图接口

接口文档

为什么要写接口文档

为什么要写接口：作为后台开发者，要将后台数据通过url链接反馈给前台

为什么要写文档：作为后台开发者，一定知道该url链接应该采用什么请求方式、提交哪些数据、返回了哪些结果。就像后台要将url链接给前台一样，前台知道应该访问什么链接，所以前台也应该知道采用什么请求方式，以及提交什么数据。

换而言之，接口文档是给 后台开发者、前台开发者、测试等各个项目相关项目组同时查看的，方便团队开发（规则是后台指定的，文档后台来写）

编写文档方式

i）采用word编写
ii）drf框架有插件，可以根据cbv的类快速生成文档
iii）采用写文档的平台

YApi平台

YApi是去哪网大前端技术中心的一个开源可视化接口管理平台

YApi项目可以搭建在任何本地或云服务器上，完成后台项目开发时的接口编写。为开发、测试等人员提供可视化的接口预览。

YApi的测试网站：http://yapi.demo.qunar.com/，我们可以通过测试网站了解YApi是如何进行接口的编写的

书写过程

1、先安装开发需要，完成接口的开发（设置后台url链接，设置请求方式、请求数据、响应结果）
2、选择一个接口平台，将后台url链接，设置请求方式、请求数据、响应结果信息变成成文档即可

接口规范

为什么要指定接口规范

　　在前后台分离情况下，后台可以采用不同的后台运用，开发出类似的功能，所以前后台请求响应的规则是一致的；如果安装一套标准来编写接口，后台不管是什么语言，前台都可以采用一样的方式进行交互。反过来，后台也不需要管前台到底采用何种方式请求（页面、工具、代码）

通用接口规范

url编写

https协议 - 保证数据安全性
api字眼 - 标识操作的是数据
v1、v2字眼 - 数据的不同版本共存
资源复数 - 请求的数据称之为资源
拼接条件 - 过滤群查接口数据（https://api.baidu.com/books/?limit=3&ordering=-price）

请求方式

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

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

get - 查 - 返回查询的对象结果
post - 增 - 返回新增的对象结果
put | patch - 改 - 返回修改的对象结果
dedlete - 删 - 返回空

响应状态码

正常响应

• 响应状态码2xx
  • 200：常规请求
  • 201：创建成功

重定向响应

• 响应状态码3xx
  • 301：永久重定向
  • 302：暂时重定向

客户端异常

• 响应状态码4xx
  • 403：请求无权限
  • 404：请求路径不存在
  • 405：请求方法不存在

服务器异常

• 响应状态码5xx
  • 500：服务器异常

响应结果

网络状态码与状态信息：2xx | 3xx | 4xx | 5xx

数据状态码：前后台约定规则 - 0:成功 1:失败 2:成功无结果

数据状态信息：自定义成功失败的信息解释(英文)

数据本体：json数据

数据子资源：头像、视频等，用资源的url链接