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.

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