软件吞噬世界，Api快速入门到放弃

🍏 一、前情提要

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

本文为api科普系列第二篇，西红柿将带领大家 快速入门api。

• API 必备工具：https://www.eolink.com/

🍐 二、快速学会 API管理工具

🍋 2.1 创建 API 项目

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

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

2.1.1 手动创建项目

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

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

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

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

🍌 2.2 添加协作成员

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

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

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Nkp5oAfH-1665301482819)(http://data.eolinker.com/AkMn3fKab4578c39c0374482b9653e3cde14cc6481e045f)]

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

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-LDNI6y1z-1665301482819)(http://data.eolinker.com/b3rqJNz6687db70bb110bf35ec8fabe6f0d1241063ee1c9)]

🥜 2.3 创建 API 文档

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

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

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

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

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

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

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-ZXY5m5wG-1665301482819)(http://data.eolinker.com/8aLuTqh8ba74a606f476a5f795ce68080b1c3d708830fa1)]

手动创建API

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

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

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-rkfymXHC-1665301482819)(http://data.eolinker.com/cGJSG3E0519825499a6435fdca9a2379a2cf3fba1c6abdd)]

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

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-6aKzirCU-1665301482819)(http://data.eolinker.com/E5Hh8tT1a696bd206b0455c5bd62997c23911781726eb6e)]

填写API文档

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

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

API 请求参数

设置请求头部（request header）

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

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

Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
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 参数：

/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文档和测试时，下方表格的参数名不需要使用{}。

API 响应内容

设置响应头部（response header）

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

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

设置响应内容（response body）

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

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

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

🍕 2.4 发起 API 测试

页面入口

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

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-cWebO0Lh-1665301482821)(http://data.eolinker.com/C5YE33X82deeb0b5fc2503950f36ce924fd4eac562fb2a1)]

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-M4G0BvcA-1665301482821)(http://data.eolinker.com/i6C2SZzaf14cc3b9944b947b7492f836a7c6afcc9c217f7)]

填写请求参数

首先填写好请求参数。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-lEOr73qx-1665301482821)(http://data.eolinker.com/VSSASJAa7fbaec4b1307a7cadba9d5336db086b8af037ad)]

请求头部

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

Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
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. 请求时间分析

🥞 2.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。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-NQNNnSHw-1665301482821)(http://data.eolinker.com/Mzcyzyvab04157a6e397864881bf24309fd4389f7b6e007)]

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

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

🍤 2.6 调用 Mock API

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

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

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

🍅 三、小结

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

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

今天的分享就到这里，如有帮助，来个点赞收藏鼓励一下作者吧!

• API 必备工具：https://www.eolink.com/