API 小白入门教程

正如汽车行业必须达到一定的规模，才能让企业只生产一个部件。软件产业现在已经足够大了，尤其当你接受所谓的“软件吞噬世界”此类的说法时更是如此。因此，和汽车工业不再生产自己的钢铁一样，大多数公司都希望利用 API 来提供更好的服务，以增强他们的产品和服务。

___《计算机网络：系统方法》的作者 Bruce Davie

API 标准化的数据传输能力，能够轻松支持支付处理、运输服务、信息传递、电子商务平台等。以及随着信息技术的蓬勃发展，API 的应用越来越广泛，了解和掌握 API的使用，也成为程序员必修课！

本文将带领大家 快速入门 API 。

演示工具：一站式 API 开发协作平台- Eolink Apikit

1、创建 API 项目

在 API 接口研发管理产品中，所有的 API 接口都是以项目的方式进行管理，因此首先需要创建一个 API 管理项目。

除了创建 API 项目，还可以创建项目组来对项目进行分类或者设置统一的用户操作权限。

手动创建项目

输入项目名称、项目类型，点击确认！

当然，你也可以选择导入第三方产品数据。除了手动创建项目，系统也提供了一键导入 Swagger、Postman、RAP、YAPI 等产品数据的功能。

API 研发管理项目列表页，点击 导入 按钮。

支持几乎所有类似的第三方。

产品	支持度	导入文件的后缀名
Eolink API研发管理	完全支持	.json
Postman V2	支持导入 API 基础信息，超过 10级分组的 API 数据将不会被导入	.json
Swagger V2	支持导入 API 基础信息	.json
Swagger V3	支持导入 API 基础信息	.json
Rest Client	支持导入 API 基础信息	.json
RAP	支持导入 API 基础信息	.json
YAPI	支持导入 API 基础信息	.zip

2、添加协作成员

您可以将团队成员添加到该项目中进行协作。注意：成员只有被添加到该项目后才能看到项目内容。

进入项目的人员管理页面，点击 添加协作成员 按钮，在弹窗中选择需要添加的成员以及赋予的角色。

系统默认有项目管理员、只读、可编辑等默认角色，您也可以根据需要创建新的自定义角色：

角色名称	权限范围
项目管理员	拥有项目内的最高权限，可以设置其他成员的权限角色
只读成员	拥有项目内的只读权限
可编辑成员	拥有项目内的读写权限
自定义角色	自定义权限

3、创建 API 文档

在 API 研发管理产品中，几乎所有的协作工作都是围绕着 API 文档进行的。

我们在接触了大量的客户后发现，采用 文档驱动 的协作模式会比 先开发、后维护文档 的方式更好，团队协作效率和产品质量都能得到提高。因此我们建议您尝试基于文档来进行工作，使用 文档驱动 方式来降低大量无意义的沟通成本。

产品支持几种创建 API 文档的方式：

1. 手动创建文档：适合所有团队；
2. 根据代码注解自动生成文档：适合使用过或正在使用 Swagger 产品来自动生成文档的团队。
3. 根据代码模板快速创建 API 文档：适合所有团队。

当您创建了 API 文档之后，您可以随时查看 API 的改动情况、根据 API 文档发起 API 测试、编写 API 测试用例、使用 Mock API 等。

如下图是在系统中管理的 API 文档，可以详细的看到 API 的描述信息、变更历史、测试用例、Mock API 等内容。

手动创建 API

在项目详情页点击左侧 API 文档功能，进入 API 管理页面，点击 添加 API，会进入 API 创建页面。

私有云产品比线上 SaaS 产品支持更多的API协议，比如 TCP、UDP、SOAP、HSF 等。

API 编辑页面中可以填写 API 文档、返回数据、额外说明等信息，您可以通过顶部的标签切换。

填写 API 文档

在 API 描述标签页中填写 API 的请求路径、API名 称、标签、负责人等基本信息信息。

1. API 状态：可以方便成员查看 API 当前所处的状态，并且进行状态流转的通知;
2. Tag 标签：可以作为 API 的备注或者是筛选条件;
3. 负责人：当 API 文档内容发生变化时，负责人会自动收到 API 变更通知。

API 请求参数

设置请求头部（request header）

您可以输入或导入请求头部。

批量导入的数据格式为 key : value ，一行一条 header 信息，如：

1 Connection: keep-alive
2 Content-Encoding: gzip
3 Content-Type: application/json
4 Date: Mon, 30 Dec 2019 20:49:45 GMT

设置请求体（request body）

请求体提供了五种类型：

1. Form-data（表单）
2. Json
3. XML
4. Raw（自定义文本类型数据）
5. Binary（字节流、文件参数）。

对于 Form-data（表单）、Json、XML 等数据类型，可以通过引用事先编辑好的 数据结构 来快速填写内容。

设置 Query 参数

Query 参数指的是地址栏中跟在问号？后面的参数，如以下地址中的 user_name 参数：

1 /user/login?user_name=jackliu

批量导入的数据格式为 ?key=value… ，通过&分隔多个参数，如：

1 api.eolinker.com/user/login?user_name=jackliu&user_password=hello

设置 REST 参数

REST 参数指的是地址栏被斜杠/分隔的参数，如以下地址中的使用大括号包裹起来的 user_name、user_password 参数：

1 /user/login/{user_name}/{user_password}
2 注意，您只需要在URL中使用{}将REST参数括起来。API文档和测试时，下方表格的参数名不需要使用{}。

API 响应内容

设置响应头部（response header）

您可以输入或导入响应头部。批量导入的数据格式为 key : value ，一行一条 header 信息，如：

1 Connection: keep-alive
2 Content-Encoding: gzip
3 Content-Type: application/json
4 Date: Mon, 30 Dec 2019 20:49:45 GMT

设置响应内容（response body）

响应内容的编写方式和请求参数的类似，响应内容提供了四种类型：

1. Json
2. XML
3. Raw（自定义文本类型数据）
4. Binary（字节流、文件参数）

对于 Json、XML 等数据类型，可以通过引用事先编辑好的 数据结构 来快速填写内容。系统也提供了导入功能方便您快速导入参数信息。

4、发起 API 测试

页面入口

进入 API 文档详情页，点击上方 测试 标签，进入 API 测试页，系统会根据API文档自动生成测试界面并且填充测试数据。

填写请求参数

首先填写好请求参数。

请求头部

您可以输入或导入请求头部。批量导入的数据格式为 key : value ，一行一条header信息，如：

1 Connection: keep-alive
2 Content-Encoding: gzip
3 Content-Type: application/json
4 Date: Mon, 30 Dec 2019 20:49:45 GMT

请求体

请求体提供了五种类型：

1. Form-data（表单）
2. JSON
3. XML
4. Raw（自定义文本类型数据）
5. Binary（字节流、文件参数）

产品中提供了的 JSON 和 XML 编辑器，当您已经在 API 文档中定义好 API 的请求数据结构时，只需要在测试界面填写各个字段的值，系统会自动转换为相应的 JSON 和 XML 结构的请求数据。

Query 参数

Query参数指的是地址栏中跟在问号？后面的参数，如以下地址中的 user_name 参数：

/user/login?user_name=jackliu

批量导入的数据格式为 ?key=value ，通过&分隔多个参数，如：

api.eolinker.com/user/login?user_name=jackliu&user_password=hello

REST参数

REST参数指的是地址栏被斜杠/分隔的参数，如以下地址中的user_name、user_password参数:

/user/login/{user_name}/{user_password}

注意，只需要在URL中使用 {} 将REST参数括起来，下方的请求参数名中不需要使用 {} 。

处理脚本

脚本分为 前置脚本 和 后置脚本 两种，分别对应 API 请求前 和 返回数据后 的两个阶段。您可以通过编写 Javascript 代码，在 API 前置脚本中改变请求参数，或者是在 API 后置脚本中改变返回结果。

脚本常用于以下几种情况：

1. API 请求前对请求参数进行复制、加解密等操作，比如进行Body进行整体签名
2. API 返回结果后对结果进行解密等

发起的API请求会依次经过以下流程。其中如果您没有编写相应的API脚本，则会略过API脚本处理阶段。

查看测试结果

填写好请求参数后，点击测试按钮即可得到测试报告，报告包括以下内容：

1. 返回头部
2. 返回内容
3. 实际请求头部
4. 实际请求内容
5. 请求时间分析

5、创建 Mock API

什么是 Mock API

在瀑布流开发模式中，如果前端开发人员需要进行页面对接，需要后端先完成 API 的开发工作，因此前后端开发的进度会互相影响。

通过 Mock API，您可以事先编写好 API 的数据生成规则，由系统动态生成 API 的返回数据。开发人员通过访问 Mock API 来获得页面所需要的数据，完成对接工作。

当项目正式发布时，只需将 Mock API 的地址前缀替换为实际的访问地址即可。

因为同一个项目中的 Mock API 的地址前缀是相同的（如mock.eolinker.com/uasyd1/…），因此可以在代码中将 Mock API 的地址前缀作为全局变量，项目上线时仅需替换变量的值即可改变整个项目的 API 请求地址前缀。

创建 Mock API

进入 API 文档详情页面，点击 Mock API 标签，点击 新建 Mock API

在弹窗中填写 Mock API 的触发条件和返回结果。

触发条件支持请求头部、请求体（Form-data、JSON）、Query 参数等。以下例子表示当 Form-data 参数中包含 user_name = jackliu 时，返回预设的 JSON 字符串。

6、调用 Mock API

进入 Mock API 列表页面，点击调用地址即可复制到剪贴板，在代码中直接对该 API 地址发起请求即可得到响应结果。

Mock API 对触发条件的优先级是：

填写了触发条件	优先级	效果
是	高	当包含了触发条件所需要的参数时，返回预期结果
	中	当所有填写了触发条件的 Mock API 都无法被触发时，触发无条件的Mock API并且返回预期结果
	低	当以上两种情况均无法触发 Mock API 时，系统返回提示信息。此时请检查请求协议、请求方法、请求参数是否符合 Mock API 的设置。

注意：如果系统无法找到匹配的 Mock API，不会返回相应的结果，因此调用 Mock API 必须保证请求的协议、请求方式（如 GET、POST...）、参数值等能够命中事先设定好的 Mock API 触发条件。

三、小结

以上就是 API 快速入门的实操小课堂。整体来看，Eolink 在改善研发人员体验方面，比较出色，前端、后端和管理者等不同的角色可以基于 Eolink app，在全新的水平上提供专业开发的能力，同时极大提高便利性，研发人员只需关注研发本身，无需花费太多精力于管理 API，从而提高团队的工作效率。

当多方（从内部开发人员到合作组织和客户）都可以访问 API 时，安全性成为关键焦点，您需要采取一切可能的措施来保护敏感数据，并确保正确分配和管理权限。基于 Eolink API 管理解决方案，可以轻松实现这一目标。

体验地址：一站式 API 开发协作平台- Eolink Apikit