A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations
0 likes166 views
The document describes an automatic link generator tool for OpenAPI specifications. It summarizes that GraphQL is gaining popularity as an alternative to REST APIs, but migrating existing REST APIs to GraphQL via tools like OpenAPI-to-GraphQL results in GraphQL schemas that lack connections between related resources. The presented link generator analyzes OpenAPI paths to identify hierarchical relationships and adds the missing link definitions to better integrate resources in the generated GraphQL schema. The tool has been tested on over 1500 real-world API specifications and was able to add links for about 34% of them.
![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](https://image.slidesharecdn.com/a-link-generator-for-increasing-the-utility-of-openapi-to-graphql-translations-200422074035/85/A-Link-Generator-for-Increasing-the-Utility-of-OpenAPI-to-GraphQL-Translations-7-320.jpg)
![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](https://image.slidesharecdn.com/a-link-generator-for-increasing-the-utility-of-openapi-to-graphql-translations-200422074035/85/A-Link-Generator-for-Increasing-the-Utility-of-OpenAPI-to-GraphQL-Translations-8-320.jpg)
![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]
}](https://image.slidesharecdn.com/a-link-generator-for-increasing-the-utility-of-openapi-to-graphql-translations-200422074035/85/A-Link-Generator-for-Increasing-the-Utility-of-OpenAPI-to-GraphQL-Translations-12-320.jpg)
![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/](https://image.slidesharecdn.com/a-link-generator-for-increasing-the-utility-of-openapi-to-graphql-translations-200422074035/85/A-Link-Generator-for-Increasing-the-Utility-of-OpenAPI-to-GraphQL-Translations-16-320.jpg)
A Link Generator for Increasing the Utility of OpenAPI-to-GraphQL Translations
- 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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