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

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

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

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

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

快速学会 API 管理工具

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

API 小白入门教程的更多相关文章

  1. 2018最新Python小白入门教程,30天学会Python

    随着Python的技术的流行,Python在为人们带来工作与生活上带来了很多的便捷,因为Python简单,学起来快,也是不少新手程序员入门的首选语言.作为一名Python爱好者,我也想跟大家分享分享我 ...

  2. 浅谈Ubuntu PowerShell——小白入门教程

    早在去年八月份PowerShell就开始开源跨平台了,但是一直没有去尝试,叫做PowerShell Core. 这里打算简单介绍一下如何安装和简单使用,为还不知道PowerShell Core on ...

  3. Vue2.0--14.小白入门教程--实例化多个vue对象,可初始化操作几种方法

    课程地址: https://study.163.com/course/courseMain.htm?courseId=1004711010 <!DOCTYPE html> <html ...

  4. 无废话ExtJs 入门教程十九[API的使用]

    无废话ExtJs 入门教程十九[API的使用] extjs技术交流,欢迎加群(201926085) 首先解释什么是 API 来自百度百科的官方解释:API(Application Programmin ...

  5. Docker入门教程(九)10个镜像相关的API

    Docker入门教程(九)10个镜像相关的API [编者的话]DockerOne组织翻译了Flux7的Docker入门教程,本文是系列入门教程的第九篇,重点介绍了镜像相关的Docker Remote ...

  6. Docker入门教程(八)Docker Remote API

    Docker入门教程(八)Docker Remote API [编者的话]DockerOne组织翻译了Flux7的Docker入门教程,本文是系列入门教程的第八篇,重点介绍了Docker Remote ...

  7. Docker入门教程(七)Docker API

    Docker入门教程(七)Docker API [编者的话]DockerOne组织翻译了Flux7的Docker入门教程,本文是系列入门教程的第七篇,重点介绍了Docker Registry API和 ...

  8. ArcGIS API for JavaScript 入门教程[0] 目录

    随时翻看. 转载注明出处,博客园/CSDN/B站:秋意正寒. Part 1 必看 ArcGIS API for JavaScript 入门教程[1] 渊源 你还真不一定知道这是啥.非得学吗? ArcG ...

  9. ArcGIS API for JavaScript 入门教程[2] 授人以渔

    这篇仍然不讲怎么做,但是我要告诉你如何获取资源. 目录:https://www.cnblogs.com/onsummer/p/9080204.html 转载注明出处,博客园/CSDN/B站:秋意正寒. ...

  10. ArcGIS API for JavaScript 入门教程[4] 代码的骨架

    [回顾与本篇预览] 上篇简单介绍了JsAPI中的数据与视图,并告诉大家这两部分有什么用.如何有机连接在一起. 这一篇快速介绍一下前端代码的骨架.当然,假定你已经熟悉HTML5.CSS3和JavaScr ...

随机推荐

  1. O-MVLL代码混淆方式

    在介绍O-MVLL之前,首先介绍什么是代码混淆以及基于LLVM的代码混淆,O-MVLL项目正是基于此而开发来的. 有关O-MVLL的概括介绍以及安装和基本使用方式,可参见另一篇随笔 https://w ...

  2. 快速入门JavaScript编程语言

    目录 JS简介 JS基础 1.注释语法 2.引入js的多种方式 3.结束符号 变量与常量 let和var的区别 申明常量 const 严格模式 use strict 基本数据类型 1.数值类型(Num ...

  3. Nmap扫描参数

    执行Nmap/nmap --help查看帮助文档,将显示Namp的用法及其功能Nmap的相关参数的含义与用法:扫描目标时用到的参数:-iL:从文件中导入目标主机或目标网段-iR:随意选择目标主机--e ...

  4. [编程基础] Python列表解析总结

    在本教程中,我们将学习使用Python列表解析(list comprehensions)相关知识 1 使用介绍 列表解析是一种基于现有列表创建列表的句法结构.列表解析提供了创建列表的简洁方法.通常需要 ...

  5. ArcGIS Python判断数据是否存在

    判断是程序编写的一个基本的操作,也是增强程序稳定性的重要方式.在ArcPy处理数据时,要保证数据存在才能做后续的操作,为源GIS提示使用arcpy自带的Exists函数可判断要素类.表.数据集.sha ...

  6. S2-048 CVE-2017-9791 远程命令执行

    漏洞名称 S2-048 CVE-2017-9791 远程命令执行 利用条件 Struts 2.3.x 开启Struts 1 plugin and Struts 1 action插件 漏洞原理 漏洞产生 ...

  7. python进阶之路3之数据类型

    内容概要 pycharm下载与使用 python语法之注释 python语法之变量与常量 python基本数据类型(先大致了解有哪些) pycharm下载与使用 1.该软件分为收费版和免费版 免费版本 ...

  8. [C#]关于逆变与协变的基本概念和修饰符in与out的意义

    协变与逆变的概念 假如两个类型X和Y具有特殊关系,X类型的每个值都能转换成Y类型.我们将I<X>向I<Y>的转换称为协变转换.反之我们将I<Y>向I<X> ...

  9. Java解题练习

    Java解题练习 1.A+B问题   解题代码: import java.util.*; public class Main { public static void main(String[] ar ...

  10. YMOI2019-5.4

    题解 YMOI2019-5.4 前言 欸,被干爆了.. 太菜了.亏我还提前看题了,还是自古大神出民间 YMOI2019的第二次考试吧.第一次没参加,这一次是第一次却出师不利..还要继续加强 还是总结一 ...