一、API使用过程中的那些“拦路虎”  

API作为开发者使用ZStack Cloud的重要桥梁，一直备受开发者的依赖与关注。随着ZStack Cloud产品版本迭代，功能愈发丰富，提供给开发者的API数量也急剧增加，目前开放使用的API数量已超过1000条大关。再加上纷繁复杂的业务场景，API调用更加灵活多变，致使开发者，尤其是入门新手，往往会在开发道路上遇到一些“拦路虎”，本想大显身手，却被束手束脚，比如：

• 组合查询条件复杂，不知道应该增加哪些条件

• API范例不够丰富，没有覆盖所有场景，无法满足自己的需求

• 遇到疑难问题，排查、咨询耗时耗力

为此，我们希望通过API Inspector功能，让开发者能够快速、便捷、场景化地了解与使用ZStack Cloud 丰富的 API 。

二、API Inspector功能亮点 

• 一键开启：一条命令，全局开启该功能

• UI可视化：以时间轴方式实时呈现API记录

• 自由操作：页面操作不受限，指哪儿查哪儿

• 一键复制：Curl命令、Request URL支持一键复制到第三方工具

• 多账户推送：不同视角下的API调用情况，一目了然

三、API Inspector功能使用

1.开启方式：一条命令，全局开启

管理员登录管理节点终端，执行以下命令，即可在ZStack Cloud云平台全局范围内一键开启/关闭API Inspector功能：

如果您为ZStack Cloud基础版/标准版/企业版用户，均可使用上述方法启用该功能。

2.API记录：自由操作，实时呈现

当API Inspector功能开启后，用户登录ZStack Cloud云平台，即可在页面上方导航栏右侧看到API Inspector功能入口。展开查看实时API记录，记录会根据调用时间流呈现。

无论“API记录”窗口打开或关闭，界面调用的API情况都会被记录下来。推荐先点击“清空记录”按钮，再在UI界面上进行相关操作，查看实时API记录，比如查询资源、增删改资源等。

API记录可根据请求类型进行筛选，显示筛选后的最近100条记录。支持以下几种请求类型：

• GET：查询类 - 查询资源

• GET-ZQL：查询类 - 通过ZQL语句查询资源

• POST：操作类 - 创建资源

• PUT：操作类 - 修改资源

• DELETE：操作类 - 删除资源

每次变更筛选条件会清空当前API记录。

图1：实时API记录

3.API详情：一键复制，快速调试

点击对应API右侧“查看详情”按钮，进入API记录详情页，可查看该API记录的详情信息，包括当前API的调用ID、请求方法、请求URL、请求头、请求体、Curl请求示例、响应结果、响应耗时等信息。其中，API调用ID可用于快速定位当前调用在管理节点前端和后端的日志记录，方便快速排查问题。对于GET-ZQL类型请求详情，特别支持查看ZQL语句，方便用户参考学习，快速掌握使用技巧，提高查询效率。所有代码段均支持复制，方便用户在第三方工具调试使用。

图2：API记录详情

4.使用建议

使用API Inspector功能会涉及大数据量传输，建议开发者在开发测试环境中使用，不建议在实际生产环境中使用。

《开发手册》依然是学习ZStack Cloud 相关 API最完备的材料。

图3：ZStack Cloud开发手册

四、API Inspector技术揭秘 

让我们借助这张图揭秘API Inspector功能是如何从技术上实现的。

图4：API Inspector技术框架

1.同步/异步API与Webhook

ZStack Cloud API 提供原生RESTful支持，分为同步API与异步API两种。对于同步API（通常为GET类型），调用方在调用返回的Response Body中可立即获得API执行结果。对于异步API，响应结果为包含轮询地址和超时时间的固定结构，可以通过轮询该地址获得异步API执行状态与结果。但轮询是一种较为低效的查询结果的方式，因此在官方实践中，通常采用Webhook方式来避免这类问题。当异步请求API指定了Webhook地址后，ZStack Cloud管理节点会在异步请求结束时主动向调用方推送响应结果。

2.GraphQL与推送机制

UI-Server中间层在API调用上进行了统一封装。

对于同步API，UI-Server底层在请求和响应阶段按照普通API请求的方式进行处理。同步API通常为查询类请求，面对复杂业务场景，查询时往往需要组合不同的API进行级联查询，UI-Server上层便采用GraphQL这种查询语言来进行处理，并通过DataLoader来解决级联引发的批量查询问题。也正因为这些技术在ZStack Cloud中的运用，开发者用户无法直接从浏览器提供的网络请求中获取页面功能在底层的API调用情况。

对于异步API，UI-Server底层在请求阶段指定了Webhook地址，同时将请求记录（唯一UUID）保存下来，当接收到ZStack Cloud管理节点主动推送的结果之后，再将该结果借助GraphQL的订阅机制，通过WebSocket推送给UI端，完成整个异步请求周期。尽管开发者用户在浏览器端可以通过“操作日志”菜单查看到操作类的组合情况和实际调用情况，但也无法解决快速调试的问题。

正因为在UI-Server中间层对API请求的封装，开发者无法直观获取原始API的请求记录，API Inspector功能应运而生。当用户开启该功能时，UI端会发起API记录的订阅，而UI-Server在底层发起API请求的同时，会向该订阅端推送请求记录，API Inspector功能核心即在于此。对于开发者而言，不同身份用户的请求条件不尽相同，也是困扰开发者的问题之一，因此订阅推送请求时，ZStack Cloud会依据登录用户Session进行区分，达到推送数据用户唯一和推送数据隔离的效果。

3.让功能更好用的细节

ZStack Cloud UI端在架构设计之初便使用了微前端（Micro Frontend）技术，主应用作为整个UI的公共基础，API Inspector功能便放置于此，作为一个公共功能模块，跟随主应用的启动而加载。在不同子应用之间切换时，也能保证API记录工作的连续性，让开发者在使用时更加顺畅。

API记录抽屉内的Dom元素，不会随着抽屉的关闭而销毁，即使关闭抽屉，也能保证记录的连续性，使得“指哪儿查哪儿”成为可能。

在API记录详情页展示的Request URL和Curl命令中，已提前针对性做好字符串转译和替换，比如将Domain替换为访问地址，以便让使用内部私有网络安装ZStack Cloud云平台的开发者在本机也能通过弹性IP直接调试使用。

在功能设计之初，API请求记录是在UI-Server请求完成后向UI端推送，若遇到网络不稳定的情况时，会让使用者有记录丢失的错觉。为了让记录更准确更实时，我们将同一条API请求，在推送消息时拆分成Request和Response两种类型，收到Request消息即展示，收到Response消息进行更新。

五、总结

云轴科技ZStack作为一家自主创新、专注产品化的云计算公司，打造较好用的云产品，降低用户云计算使用门槛，是我们一直以来秉持的理念和践行方向。相信API Inspector功能的推出，会让ZStack Cloud开发者用户的工作更加便利高效。未来，我们会继续推出更多丰富好用的云计算产品功能，为用户创造价值。