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? ct=17&pn=0&tn=ikaslist&rn=10&fr=wwwt&word=%E6%B5%8B%E8%AF%95

将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"}
    
  • text/plain(了解),纯文本格式,一般使用raw-Text;

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方式):点击查看

本文是否对您有帮助?
 有帮助
 没帮助
您是否遇到了以下问题?
如需获取即时帮助,请联系技术支持