1.2 阅读API接口文档

本节主题：1.2 阅读API接口文档

课程讲师：Charlie

观看地址：点我进入

1 本节要点

如何阅读接口文档
接口文档实例讲解

2 课前准备

2.1 接口测试工具

提前准备一个接口测试工具，以下工具任选其一：

POSTMAN （可选）

POSTMAN是最好用的接口测试工具！

点击此链接Postman | Download Postman App进入Postman官网下载页面，选择相应的版本（操作系统及 32位/64位）并安装；

正常的话，浏览器会自动识别处你的电脑系统，本教程用macOS电脑打开的，图中圈出的地方会自动识别电脑系统；

Windows用户需要选择32位或是64位版本，你需要先查看你所使用的电脑是32位还是64位处理器，如果你不清楚，可以在电脑设置中查看；

点击下载，直接打开压缩包安装即可。

安装后打开软件需要注册，分别填写邮箱、用户名、密码，下两个框均需要勾选，然后点击橙色按钮，注册一个免费账户。

POSTWOMAN （可选）

是一个用于替代Postman,免费开源、轻量级、快速且美观的API调试工具。能帮助程序员节省时间,提升工作效率；

无需下载，访问官网即可使用！

点击访问：POSTWOMAN官网

Apizza（可选）

极客专属的接口协作管理工具；

点击访问：Apizza官网

ApiPost（可选）

ApiPost是一个支持团队协作，并可直接生成文档的API调试、管理工具，支持模拟POST、GET、PUT等常见请求，是后台接口开发者或前端、接口测试人员不可多得的工具；

点击访问：ApiPost官网

2.2 接口准备

阅读简道云帮助文档，了解什么是API：点击查看
阅读简道云API相关功能文档，看不懂的地方可以先记住，上完课再看看是否解决了疑问
公共接口，开发文档地址：点击查看

-课前找到两个API接口，可以是简道云的，也可以是公司内部系统的，也可以是第三方API接口（不知道哪里找？阿里云市场有很多可以免费测试的第三方接口哦～点击查看）

3 课程内容

3.1 如何看接口文档？

API接口文档一般分为接口描述、接口地址、请求方法、请求参数、响应内容、错误代码、实例几个部分：

接口描述：简单描述接口的逻辑和作用。例如说明这是一个发送消息的接口、查询天气的接口；

接口地址：这个地址表示的是网络地址，即url，我们需要调用接口url，获取响应内容；

请求方法：常见的请求方法为GET和POST，其他的方式见下图；

请求参数：用来传递信息的变量。即需要请求的字段名的名称和规则：都是哪些字段，字段的类型是什么，是否必填字段等等；

URL传参
Headers 请求头
Body 请求内容

响应内容：接口返回的字段名称和规则；

错误代码：对接口的错误用代码进行归类，以便能快速找到错误原因，解决问题；

实例：实际调用时的响应的内容。

这里需重点掌握 GET 和 POST 请求方式！

3.2 GET请求

GET通常用于获取服务端数据：

GET方式在url后面拼接参数，只能以文本的形式传递参数；
传递的数据量小，4kb左右（不同浏览器会有差异）；
安全性低，会将信息显示在地址栏；
速度快，通常用于对安全性要求不高的请求；
GET请求也可以有Headers参数

GET请求可以传递参数，一般的传递方式为 URL传参，例如：

百度知道的搜索地址：https://zhidao.baidu.com/search

当进行搜索后的地址：https://zhidao.baidu.com/search? lm=0&rn=10&pn=0&fr=search&ie=gbk&word=%BC%F2%B5%C0%D4%C6

将URL进行拆分：

https://zhidao.baidu.com

/search

lm=0

&rn=10

&pn=0

&fr=search

&ie=gbk

&word=%BC%F2%B5%C0%D4%C6

URL解析：

请求域名（Host）：https://zhidao.baidu.com
请求路径：/search

(有的文档需要自己域名+路径，也有的文档会提供完整的接口地址，例如简道云/钉钉)

？代表开始传参
& 代表下一个参数
请求参数：

参数名	值
lm	0
rn	10
pn	0
fr	search
ie	gbk
word	%BC%F2%B5%C0%D4%C6

在GET请求中，遇到参数 / Params / Querys 均是以 URL传参的形式进行传递！

注意，在POSTMAN中，可以直接用 URL传参形式，也可以在Params处填写KEY和VALUE，会自动进行拼接（演示）！

3.3 POST请求

post提交数据相对于get的安全性高一些。（注意：抓包软件也会抓到post的内容，安全性要求高可以进行加密）；
传递数据量大，请求对数据长度没有要求；
用于密码等安全性要求高的场合，提交数据量较大的场合，如上传文件，发布文章等。

POST请求一般由Url 、 Headers 、 Body组成，如果在POST请求的接口文档里遇到 Params / Querys 则需以像GET请求一样使用URL参数传递参数，而POST请求的接口文档里面的参数一般指Body！

使用URL传参的接口：

接口地址

使用Body传参的接口：

接口地址

POST请求不同的请求格式：

application/json，JSON数据格式，一般使用raw-JSON，最常见的格式，我们后期调用接口和自己开发接口，均是以JSON为主；

如下所示，参数1的key：name，参数1的value：ziv，参数2的key：password，参数2的value：123

{"name":"ziv","password":"123"}

如下所示，参数1的key：data_id，参数1的value：5398d19a9318483922

{"data_id":"5398d19a9318483922"}

name:ziv,password:123

text/xml（了解），XML数据格式，一般使用raw-XML；

<?xml version="1.0" encoding="UTF-8" ?>
	<name>ziv</name>
	<password>123</password>

multipart/form-data（了解），它会将表单的数据处理为一条消息，以标签为单元，用分隔符分开。由于有boundary隔离，所以multipart/form-data既可以上传文件，也可以上传键值对，它采用了键值对的方式，所以可以上传多个文件；

application/x-www-from-urlencoded（了解），会将表单内的数据转换为键值对，&分隔。接口地址

3.4 文档讲解

以钉钉文档为例讲解接口（GET方式）：点击查看

https://oapi.dingtalk.com/gettoken?appkey=key&appsecret=secret

https://oapi.dingtalk.com host 域名
/gettoken 路径
GET请求，URL传参
?appkey=key&appsecret=secret
？代表开始URL传参， =前面的是参数的key（参数名），=后面的是参数的value（参数- 值）
&代表下一个参数

以阿里云API市场为例讲解接口（POST方式）：点击查看