Web API 接口

目录

• 接口
• 开发阶段接口测试工具
• 接口文档
• RESTful API 设计规范
• 总结

接口

接口概念：前台与后台进行信息交互的媒介 - url链接

接口组成：

• url 链接 - 长得像返回数据的url链接
• 请求方式 - get(查)、post(增)、put(整体改)、patch(局部改)、delete(删)
• 请求参数 - 拼接参数、数据包参数(urlencoded、form-data、json)
• 响应结果 - 响应的 json 或者 xlm 数据

开发阶段接口测试工具

Postman

接口文档

1. 为什么要写接口文档?

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

2. 编写文档

   • 采用 word 编写
   • drf 框架有插件，可以根据 CBV 的类快速生成文档
   • 采用文档的平台

3. 书写过程

   • 先安装开发需要，完成接口的开发（设置后台url链接，设置请求方式、请求数据、响应结果）

   • 选择一个接口平台，将后台url链接，设置请求方式、请求数据、响应结果信息变成成文档即可

RESTful API 设计规范

1. 为什么要指定接口规范?

   在前后台分离情况下，后台可以采用不同的语言运用，开发出类似的功能，所以前后台请求响应的规则是一致的；

   如果按照一套标准来编写接口，后台不管是什么语言，前台都可以采用一样的方式进行交互。

   反过来，后台也不需要管前台到底采用何种方式请求（页面、工具、代码）

2. 通用的接口规范：Restful 接口规范 - 规定了url如何编写；请求方式的含义；响应的数据规则

   1. url 编写

      https协议 - 保证数据安全性

      api字眼 - 标识操作的是数据

      v1、v2字眼 - 数据的不同版本共存

      资源复数 - 请求的数据称之为资源

      拼接条件 - 过滤群查接口数据（https://api.baidu.com/books/?limit=3&ordering=-price）

      # 版本：应该将API的版本号放入URL
      http://www.example.com/app/1.0/apples
      http://www.example.com/app/1.1/apples
      http://www.example.com/app/2.0/apples
          
      # 路劲：对于一个简洁结构，你应该始终用名词。 此外，利用的HTTP方法可以分离网址中的资源名称的操作。
      GET /products ：将返回所有产品清单
      POST /products ：将产品新建到集合
      GET /products/4 ：将获取产品4
      PATCH /products/4 将更新产品4（部分属性更新）
      PUT  /products/4：将更新产品4 （全部属性更新）
      

   2. 请求方式

      /books/ - get - 群查

      /books/(pk)/ - get - 单查

      /books/ - post - 单增

      /books/(pk)/ - put - 单整体改

      /books/(pk)/ - patch - 单局部改

      /books/(pk)/ - delete - 单删

      请求方法	请求地址	后端操作
      GET	/students	获取所有学生
      POST	/students	增加学生
      GET	/students/1	获取编号为1的学生
      PUT	/students/1	更新编号为1的学生（全部属性）
      DELETE	/students/1	删除编号为1的学生
      PATCH	/students/1	更新编号为1的学生（部分属性）

   3. 响应结果

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

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

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

      数据本体：json数据

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

      # 状态码
      200 OK - [GET]：服务器成功返回用户请求的数据
      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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
      

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

总结

接口：

概念：前后台数据交互的桥梁
组成：url链接 + 请求方法 + 请求数据 + 响应结果
文档：将接口的四个组成部分书写成一个使用文档
工具：Postman

Restful 接口规范：

url链接：https、api、books、v1、?limit=3
		https://www.baidu.com/api/v1/books/?limit=3
请求方式：get、post、put、patch、delete
		用不同请求方式代表操作资源的不同目的
响应结果
		网络状态码，状态信息 - 规定好的
		数据状态码，状态信息 - 开发自己约定的
		数据本地 - json数据
		子资源 - 图片、视频返回资源的url链接