[논문 리뷰] A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations

Dominik Kus, István Koren외 1명|arXiv (Cornell University)|2020. 01. 01.

Scientific Computing and Data Management참고 문헌 2인용 수 1

한 줄 요약

이 논문은 OpenAPI 사양에 링크 정의를 자동으로 추가하여 OpenAPI-to-GraphQL 번역의 품질을 향상시키는 오픈소스 도구인 OpenAPI-Link-Generator를 제안한다. 경로 계층과 매개변수 일관성을 분석함으로써, APIs.guru 디렉터리에 속한 API의 34%에 대해 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-to-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-to-GraphQL 래퍼의 사용성에 얼마나 기여할 수 있나요?
• RQ4 명시적 메타데이터 없이도 효과적으로 REST 엔드포인트 간의 계층적 관계를 유추할 수 있는 히ュ리스틱은 무엇인가요?
• RQ5 실제 API 중에서 자동 링크 보강이 도움이 되는 경우는 얼마나 되나요?

주요 결과

• OpenAPI-Link-Generator는 APIs.guru 디렉터리에 포함된 분석 대상 1,568개 OpenAPI 문서 중 34%에 대해 7,500개 이상의 링크 정의를 추가하였다.
• 이 도구는 GraphQL 래퍼 내 쿼리 표현력에 크게 기여하여, 한 번의 요청으로 저장소와 그 브랜치를 모두 가져오는 중첩 쿼리가 가능해졌다.
• 누락된 링크 정의가 OpenAPI-to-GraphQL 번역에서 과소 검색과 쿼리 표현력 저하의 주요 원인이었다.
• 경로 계층과 매개변수 일관성 기반의 히ュ리스틱 접근 방식이 대부분의 경우 정확한 관계를 성공적으로 유추하였으며, 잘못된 결과는 거의 발생하지 않았다.
• 도구의 영향은 GitHub와 같은 실제 API를 대상으로도 검증되었으며, 쿼리 사용성 향상에 실질적인 기여를 했다.
• CLI, npm 모듈, 웹 서비스 형태로도 제공되어, 기존 API 개발 워크플로우에 널리 통합되고 활용될 수 있다.