Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
A Link Generator
for Increasing the
Utility of
OpenAPI-to-
GraphQL
Translations
Dominik Kus,
István Koren,
Ralf Klamma
Mot...
Upcoming SlideShare
Loading in …5
×

of

A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 1 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 2 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 3 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 4 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 5 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 6 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 7 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 8 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 9 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 10 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 11 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 12 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 13 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 14 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 15 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 16 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 17 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 18 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 19 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations Slide 20
Upcoming SlideShare
What to Upload to SlideShare
Next
Download to read offline and view in fullscreen.

0 Likes

Share

Download to read offline

A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations

Download to read offline

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.

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all
  • Be the first to like this

A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations

  1. 1. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 1 A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations The Web Conference 2020: Developers Track Dominik Kus, István Koren, Ralf Klamma kus,koren,klamma@dbis.rwth-aachen.de Chair of Computer Science 5 Information Systems & Databases RWTH Aachen University April 20, 2020
  2. 2. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 2 Overview Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today!
  3. 3. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 3 Motivation The Web is powered by APIs APIs enable all kinds of applications (mobile, web, microservices, . . . ) Today, most of them are REST(-like) Limitations Overfetching, e.g. when only name of project required Underfetching, e.g. /projects/12 /projects/12/contributors
  4. 4. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 4 Introduction to GraphQL Alternative to REST: GraphQL Released in 2015 by Facebook Quickly gaining popularity Figure: Examples of GraphQL Adopters
  5. 5. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 4 Introduction to GraphQL Alternative to REST: GraphQL Released in 2015 by Facebook Quickly gaining popularity Figure: Examples of GraphQL Adopters Query language approach Mitigates problems of over- and underfetching Other advantages (tool support, documentation, developer friendliness, . . . ) We want to leverage these advantages for existing APIs!
  6. 6. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 5 Migration from REST to GraphQL Automatic migration Starting point: machine-readable documentation For GraphQL: GraphQL Schema For REST: OpenAPI 1 https://github.com/IBM/openapi-to-graphql
  7. 7. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 5 Migration from REST to GraphQL Automatic migration Starting point: machine-readable documentation For GraphQL: GraphQL Schema For REST: OpenAPI Open-source wrapper generator OpenAPI-to-GraphQL1 [Wittern et al., 2018] 1 https://github.com/IBM/openapi-to-graphql
  8. 8. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 6 OpenAPI-to-GraphQL Open-source wrapper generator OpenAPI-to-GraphQL2 [Wittern et al., 2018] Proxies between GraphQL client and REST API GraphQL Client GraphQL Wrapper REST API GraphQL query REST query REST response GraphQL response 2 https://github.com/IBM/openapi-to-graphql
  9. 9. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 7 Why Links are so important If we use OpenAPI-to-GraphQL on most documentations, queries look somewhat like this Listing 1: Query without links { project(projectId: 12) { name } projectContributors (projectId: 12) { name } } Equivalent in REST: /projects/12 /projects/12/contributors No over- or underfetching
  10. 10. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 7 Why Links are so important If we use OpenAPI-to-GraphQL on most documentations, queries look somewhat like this Listing 2: Query without links { project(projectId: 12) { name } projectContributors (projectId: 12) { name } } But: No connection between a project and its contributors Counter-intuitive
  11. 11. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 8 OpenAPI Link Definitions OpenAPI Paths /project/{id} /project/{id}/contributors Parameters: . . . Response Types: . . . . . . Parameters: . . . Response Types: . . . . . . type Project { id: ID name: String }
  12. 12. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 8 OpenAPI Link Definitions OpenAPI Paths /project/{id} /project/{id}/contributors Parameters: . . . Response Types: . . . . . . Parameters: . . . Response Types: . . . . . . Link type Project { id: ID name: String contributors: [Person] }
  13. 13. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 9 Missing link definitions As shown: link definitions required for nested data New feature in OpenAPI 3.0 Basically non-existent in real-world documentations3 OpenAPI Other Unknown Total 1.1 1.2 2.0 3.0 Count 1 44 1106 52 185 190 1578 Percentage 0.1% 2.8% 70.1% 3.3% 11.7% 12.0% 100% Only 3 (!) documents contain links ⇒ Automatic Link Generation 3 Based on over 1500 documentations in the public https://apis.guru OpenAPI directory
  14. 14. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 10 Demo https://openapi-link-generator.herokuapp.com/
  15. 15. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 11 Demo: Example Query Listing 3: Before { project(projectId: 12) { name } projectContributors (projectId: 12) { name } } Listing 4: After { project(projectId: 12) { name contributors { name } } }
  16. 16. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 12 Automatic Link Generation Solution: OpenAPI-Link-Generator Takes OpenAPI as input and augments it with link definitions Available via npm4 Can be used as Node.js library or command line tool Also available as Web tool5 Concept Forward slash implies hierarchical relationship [Massé, 2012] e.g. /project and /project/contributors Add links to paths in such a relationship Consider path parameters in this process 4 https://www.npmjs.com/package/openapi-link-generator 5 https://openapi-link-generator.herokuapp.com/
  17. 17. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 13 Evaluation of the Link Generator We tested it on over 1500 real-world API documentations6 Links added to about 34% of API documentations 0 2 4 6 8 0 0.2 0.4 0.6 0.8 Number of paths in OpenAPI doc. Numberoflinksadded 6 Based on the APIs.Guru OpenAPI directory
  18. 18. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 14 Conclusion: Try it out today! GraphQL is quickly gaining popularity Has advantages over REST Big API providers are migrating to it (e.g. GitHub) OpenAPI-to-GraphQL makes an existing REST API available over GraphQL OpenAPI link definitions improve the quality of the generated schema However, they are rarely used Our link generator tool adds those automatically Tested on real-world documentations More information in the accompanying article https://www.npmjs.com/package/openapi-link-generator https://openapi-link-generator.herokuapp.com/ https://github.com/rwth-acis/openapi-link-generator
  19. 19. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 15 References Massé, M. (2012). REST API design rulebook. O’Reilly, Farnham. Wittern, E., Cha, A., and Laredo, J. A. (2018). Generating GraphQL-Wrappers for REST(-like) APIs. In Mikkonen, T., Klamma, R., and Hernández, J., editors, Web Engineering, volume 10845 of Lecture Notes in Computer Science, pages 65–83, Cham. Springer International Publishing.
  20. 20. A Link Generator for Increasing the Utility of OpenAPI-to- GraphQL Translations Dominik Kus, István Koren, Ralf Klamma Motivation Introduction to GraphQL Migration from OpenAPI to GraphQL Why Links are so important The Link Generator Conclusion: Try it out today! Lehrstuhl i5 Information Systems and Databases 16 The End

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.

Views

Total views

97

On Slideshare

0

From embeds

0

Number of embeds

1

Actions

Downloads

0

Shares

0

Comments

0

Likes

0

×