[论文解读] A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations

Dominik Kus, István Koren+1 more|arXiv (Cornell University)|Jan 1, 2020

Scientific Computing and Data Management参考文献 2被引用 1

一句话总结

本文提出 OpenAPI-Link-Generator，一款开源工具，可自动为 OpenAPI 规范添加链接定义，以提升 OpenAPI 到 GraphQL 的转换质量。通过分析路径层级结构与参数一致性，该工具在 APIs.guru 目录中 34% 的 API 中添加了超过 7,500 个链接，显著提升了 GraphQL 包装器的实用性，且无需修改底层服务。

ABSTRACT

Standardized interfaces are the connecting link of today's distributed systems, facilitating access to data services in the cloud. REST APIs have been prevalent over the last years, despite several issues like over- and underfetching of resources. GraphQL enjoys rapid adoption, resolving these problems by using statically typed queries. However, the redevelopment of services to the new paradigm is costly. Therefore, several approaches for the successive migration from REST to GraphQL have been proposed, many leveraging OpenAPI service descriptions. In this article, we present the findings of our empirical evaluation on the APIs.guru directory and identify several schema translation challenges. These include less expressive schema types in GraphQL, as well as missing meta information about related resources in OpenAPI. To this end, we developed the open source Link Generator, that analyzes OpenAPI documents and automatically adds links to increase translation utility. This fundamentally benefits around 34% of APIs in the APIs.guru directory. Our findings and tool support contribute to the ongoing discussion about the migration of REST APIs to GraphQL, and provide developers with valuable insights into common pitfalls, to reduce friction during API transformation.

研究动机与目标

• 识别并解决使用 OpenAPI 文档将 REST API 映射到 GraphQL 时的模式转换挑战。
• 通过解决资源间缺失的语义关系，提升 OpenAPI 到 GraphQL 包装器的实用性。
• 通过自动链接生成实现嵌套的、分层的查询，减少客户端的过度获取和获取不足。
• 提供一种可扩展的自动化解决方案，增强现有 OpenAPI 规范，而无需修改后端服务。
• 通过提升工具互操作性，支持可持续、低摩擦的从 REST 到 GraphQL 的迁移。

提出的方法

• 分析 APIs.guru 目录中的 1,568 份 OpenAPI 文档，识别缺失链接与模式转换问题。
• 基于 URI 路径层级结构（例如 /A 和 /A/B）应用启发式方法，推断端点之间的潜在父子关系。
• 通过名称和模式结构匹配相关端点之间的参数，确保生成的 GraphQL 模式中查询映射的一致性。
• 解析 OpenAPI 文档中的内部 JSON 引用，以在链接推断过程中支持复杂且可重用的模式定义。
• 使用 OpenAPI 3.0 的链接规范，在 OpenAPI 格式中生成将父资源映射到子资源的链接定义。
• 在真实世界 API 上评估该工具，并通过数据集中的链接数量与覆盖率来衡量其影响。

实验结果

研究问题

• RQ1 将基于 OpenAPI 的 REST API 转换为 GraphQL 时，主要的模式转换挑战是什么？
• RQ2 在真实世界的 OpenAPI 规范中，资源之间缺失的语义关系有多普遍？
• RQ3 自动化链接生成在多大程度上能提升 OpenAPI 到 GraphQL 包装器的可用性？
• RQ4 哪些启发式方法能有效推断 REST 端点之间的分层关系，而无需显式元数据？
• RQ5 有多少真实世界的 API 可以从其 OpenAPI 文档的自动化链接增强中受益？

主要发现

• OpenAPI-Link-Generator 在 APIs.guru 目录中分析的 1,568 份 OpenAPI 文档中的 34% 上添加了超过 7,500 个链接定义。
• 该工具显著提升了 GraphQL 包装器中的查询表达能力，支持如单个请求中获取仓库及其分支的嵌套查询。
• 缺失的链接定义是 OpenAPI 到 GraphQL 转换中导致获取不足和查询表达能力降低的主要原因。
• 基于路径层级结构和参数一致性的启发式方法在大多数情况下成功推断出有效关系，且未产生误报。
• 该工具在真实世界 API（包括 GitHub）上的影响已得到验证，显著提升了查询可用性。
• 该工具以命令行界面、npm 模块和 Web 服务的形式提供，支持广泛采用，并可轻松集成到现有 API 开发工作流中。