API结果过滤器

更新时间:

同个API在不同使用的场景中,默认的返回结构不一定能够满足调用者实际的需求,因此我们支持通过配置过滤器的方式,使用户可以对API返回的原始结构进行灵活的转换,减少用户API对接及二次开发的成本。

使用方式

正确配置过滤器并生效后,会对返回结果自动进行格式转换。

结果示例

某个API原始返回结构如下:

image.png

  • code:返回状态码 SUCCESS/ERROR。

  • data:返回的数据,根据数据源类型不同结构也可能有所不同,一般为ArrayList或者jsonObject结构。

  • traceId:本次调用追踪的唯一ID。

  • message:当code为ERROR会在message里返回错误原因。

现在API使用者希望去掉code、traceId等字段的封装只返回其中data的部分。当正确配置过滤器后,返回结构如下:

image.png

可以看到返回结果中只剩下了data字段里的内容,无需用户再手动转换。

配置方式介绍

API开发过程配置过滤器

在API开发过程中配置过滤器,配置完成后对所有调用都会生效。​

使用方式:

image.png

在API创建/编辑过程中,第三步【API配置及测试】页面,点击【返回内容】左上方【过滤器】按钮启用过滤器。

过滤器有两种设置方式:

  1. 格式处理:使用指定的方式对返回结果进行处理,分别是过滤code字段、过滤message字段、过滤traceId字段以及仅返回data内容,支持多选

  2. 自定义逻辑:使用自定义脚本的方式,对整个返回数据的结构进行转换。目前支持js函数,后续会开放对更多种脚本语言的支持

自定义逻辑的js函数脚本示例:

function filter(response) {
  // 获取返回结果data中第一组数据
  var data = response.data[0];
  // 拼接证件号码和客户名称后返回结果
  return data.zzhm + " : " + data.khmc;
}

使用上述脚本执行转换的结果:

image.png

设置完成后过滤器生效,关闭过滤器按钮后之后失效。

已获授权API配置过滤器

调用者对于获得授权的API,可以再单独设置一个过滤器,此过滤器只有在当前获得授权的应用调用API时才会失效,不会影响API本身的返回结构,也不会影响其他的应用对该API调用。

使用方式:

在【已获授权API】列表页,找到对应获得授权的API,点击右侧【操作】功能列中的【测试】,进入已获授权API测试页。

image.png

在已获授权API【测试】页面,点击打开【过滤器按钮】,便可配置过滤器,配置的方法和API开发过程的过滤器相同。

image.png

说明

如果一个获得授权的API已经在开发过程中开启了过滤器,那么再开启应用授权过滤器后,两个过滤器会同步生效:应用授权过滤器会对API由过滤器转换后的结果,按照设置的方式进行再次过滤,最终返回给调用方。