[论文解读] Automatically Extracting Web API Specifications from HTML Documentation

Jinqiu Yang, Erik Wittern+3 more|arXiv (Cornell University)|Jan 26, 2018

Web Data Mining and Analysis参考文献 21被引用 3

一句话总结

该论文提出 D2Spec，一种基于机器学习的工具，可自动从基于 HTML 的 API 文档中提取 Web API 端点规范，包括基础 URL、路径模板和 HTTP 方法。在 120 个 API 上的评估显示，D2Spec 在基础 URL 上达到 87.5% 的精确率，在路径模板上达到 81.3% 的精确率和 80.6% 的召回率，在 HTTP 方法上达到 84.4% 的精确率和 76.2% 的召回率，证明其在从非结构化文档中挖掘规范方面的有效性。

ABSTRACT

Web API specifications are machine-readable descriptions of APIs. These specifications, in combination with related tooling, simplify and support the consumption of APIs. However, despite the increased distribution of web APIs, specifications are rare and their creation and maintenance heavily relies on manual efforts by third parties. In this paper, we propose an automatic approach and an associated tool called D2Spec for extracting specifications from web API documentation pages. Given a seed online documentation page on an API, D2Spec first crawls all documentation pages on the API, and then uses a set of machine learning techniques to extract the base URL, path templates, and HTTP methods, which collectively describe the endpoints of an API. We evaluated whether D2Spec can accurately extract endpoints from documentation on 120 web APIs. The results showed that D2Spec achieved a precision of 87.5% in identifying base URLs, a precision of 81.3% and a recall of 80.6% in generating path templates, and a precision of 84.4% and a recall of 76.2% in extracting HTTP methods. In addition, we found that D2Spec was useful when applied to APIs with pre-existing API specifications: D2Spec revealed many inconsistencies between web API documentation and their corresponding publicly available specifications. Thus, D2Spec can be used by web API providers to keep documentation and specifications in synchronization.

研究动机与目标

• 解决尽管广泛使用 Web API，但可机器解析的 Web API 规范仍然稀缺的问题。
• 通过自动化从现有 HTML 文档中提取规范，减少创建和维护 API 规范所需的手动工作量。
• 通过检测差异，提高 Web API 文档与已发布规范之间的一致性。
• 通过从公开文档生成符合 OpenAPI 标准的规范，支持更广泛的 API 消费工具。

提出的方法

• D2Spec 首先爬取与种子 API 文档页面关联的所有文档页面。
• 它应用一组机器学习模型，从自由文本和 HTML 结构中识别并提取基础 URL。
• 通过从多个示例 URL 中进行模式识别和推理，提取路径模板，利用语法和结构线索。
• 通过分析文本上下文及与路径模板的接近程度，使用自然语言处理和基于规则的过滤来识别 HTTP 方法。
• 该方法可处理两种不同的文档风格：基于示例的（如 GitHub）和基于参考的（如 Instagram）。
• 系统使用启发式方法和训练数据，实现对不同 API 提供商和文档布局的泛化。

实验结果

研究问题

• RQ1 机器学习技术能否准确地从半结构化的 HTML API 文档中提取基础 URL？
• RQ2 在文档中，基于示例 URL 和周围文本，路径模板能在多大程度上被推断出来？
• RQ3 能否从路径描述附近的文本上下文中准确识别出 HTTP 方法？
• RQ4 D2Spec 能否检测出现有公开 API 规范与其对应文档之间的不一致？
• RQ5 该方法在不同 API 提供商和文档风格之间具有多大程度的泛化能力？

主要发现

• D2Spec 在 120 个 Web API 上识别基础 URL 的精确率达到 87.5%，表明其在 URL 提取方面具有很强的可靠性。
• 该工具在生成路径模板方面实现了 81.3% 的精确率和 80.6% 的召回率，表明其能有效从示例 URL 和结构模式中进行推断。
• 在 HTTP 方法提取方面，D2Spec 达到了 84.4% 的精确率和 76.2% 的召回率，证明其能从上下文线索中实现稳健检测。
• 评估揭示了现有公开 API 规范与其对应文档之间存在显著不一致，凸显了 D2Spec 在验证方面的价值。
• D2Spec 在 98 个不同的 API 提供商中成功实现泛化，显示出对多样化文档结构和风格的适应能力。