API-diff：用于JSON API并行评估的工具

TL; DR：Radar构建了一个开源工具，用于执行JSON API的并行评估。我们希望您也觉得它有用。

雷达工程师需要一个工具来并行评估我们最近发布的地理编码API套件的服务更改。我们找不到合适的应用程序，因此我们编写了自己的非常有想象力的API-diff。我们很荣幸在npm上发布它，并在GitHub上开源。

控制台模式下api-diff的屏幕快照，比较了发送到两个不同api服务器的相同API请求

我们在Pelias地理编码器上的工作促进了api-diff的开发，但它可与任何JSON HTTP API一起使用。这篇文章主要关注我们如何针对公共Pelias API使用它，但是该工具本身是通用的。它可以并且已经用于Radar内部的各种JSON API。

地理编码器是一款软件，可以将自由格式的字符串转换为具有与该地点相关的结构化元数据的地球坐标。例如，＆＃34; 20 Jay St＆＃34;变成＆＃34; 40.7041，-73.9867＆＃34 ;，以及它是位于美国纽约州纽约市布鲁克林的确切街道地址的元数据。地理编码器是具有挑战性的软件，因为在现实世界中，地址和查询都是乱七八糟的。

很难针对查询的每种编写方式进行详尽的测试。 Pelias目前有大量的回归测试，但是我们需要一个工具，该工具可以让我们了解排名的变化将如何影响没有经过验证的黄金结果的现实查询。

输入api-diff，这是一个令人厌烦命名的工具套件，用于评估质量或对JSON API端点之间的更改进行排名。 api-diff可以：

允许人类记分员使用键盘快捷键快速将差异分为正数，中性或负数

您只需要启动一个查询列表（一个CSV或URL路径），以及一个服务器的两个运行副本，并在它们之间进行一些更改即可。

在Radar，api-diff的两个主要用例是1）当我们对Pelias中的解析和排名算法进行代码更改时，或2）当我们更新搜索索引中的数据时。在这两种情况下，我们都希望查看搜索结果中发生了什么变化。进行排名更改时，通常在改进的查询和一些意外损失之间要权衡取舍，因此我们可以使用api-diff提供更定量的答案，以确定改进是否大于损失足以进行更改。在更新索引中的数据时，我们通常期望质量和覆盖率稳定增长，并且大多数情况下都在寻找令人惊讶的回归，这通常是由数据格式的变化引起的。

api-diff \＃这些可以是任何可访问的http服务器，有时我们会根据产品索引运行\ --new.host localhost：3100 \ --old.host localhost：4100 \＃csv输入，使用标题作为查询参数键\ --input_csv〜/ RadarCode / geocode-acceptance-tests / input / addresses.csv \＃重新映射csv列＆＃34; query＆＃34;查询参数＆＃34; text＆＃34; \ --key_map query = text \＃在我们的主机上针对/ v1 / search运行\ --endpoint / v1 / search \＃附加到每个查询的附加选项\ --extra_params sources = oa，osm \＃忽略所有名为计算diff \ --ignored_fields bbox几何归因时间戳\＃将结果精简到地址键下的第一个条目`---response_filter＆＃39; $。addresses [0]＆＃39; \＃输出交互式html差异。其他选项是text和json \ --output_mode html \ --output_file diffs.html

可以使用npm install -g @ radarlabs / api-diff将api-diff安装为命令行工具。如果您的服务器需要API密钥，则需要为其创建配置文件。

我们的工作流程是使用api-diff HTML输出模式的交互式评估功能。我们使用键盘快捷键在浏览器中手动评估每个更改。完成后，我们将检查获胜和失败的次数，以就是否继续进行此更改做出明智的决定。通常，在进行评估之前，我们会很久以前就注意到需要处理一些意外更改，因此我们会尽早退出评估并进行修复，然后再次进行评估。如果HTML输出模式再次出现，它将记住我们过去所做的质量判断，因此评估任务第二次可能会更快。

我们还可以将差异和评估输出保存到JSON文件中，以便与合作者共享。例如，这是我们正在努力整合到Pelias中的更改的评估差异。将其加载到https://radarlabs.github.io/api-diff/compare.html中，看看您是否同意我们的评估。

我们有机会在pelias-api，pelias-parser和radar.io的应用服务器上使用此工具。 在每种情况下，它使我们了解了我们无法解决的质量变化。 我们希望它对其他人也有用。 您有想要看到的功能吗？ 随时在我们的GitHub存储库上打开一个问题。