[論文レビュー] 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仕様にリンク定義を自動で追加することで、OpenAPIからGraphQLに変換する際の品質を向上させるオープンソースツール「OpenAPI-Link-Generator」を提案する。パスの階層構造とパラメータの一貫性を分析することで、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へのラッパーの有用性を向上させること。
• 自動リンク生成によりネストされた階層クエリを可能にすることで、クライアント側の過剰取得および不足取得を低減すること。
• バックエンドサービスの変更を要しない、スケーラブルで自動化されたソリューションを提供すること。
• ツール間相互運用性を向上させることで、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ラッパーにおけるクエリの表現力が顕著に向上し、1回のリクエストでリポジトリとそのブランチを取得するようなネストされたクエリが可能になった。
• 欠落したリンク定義が、OpenAPIからGraphQLへの変換における不足取得とクエリ表現力の低下の主な要因であった。
• パス階層とパラメータの一貫性に基づくヒューリスティクスアプローチは、偽陽性を伴わず大多数のケースで有効な関係を正しく推定できた。
• GitHubを含む実世界のAPIでもツールの影響が検証され、クエリの使いやすさに明確な改善が見られた。
• CLI、npmモジュール、Webサービスとしての提供により、広範な採用と既存のAPI開発ワークフローへの統合が可能になった。