Abstract
GraphQL is a query language for APIs and a runtime to execute queries. Using GraphQL queries, clients define precisely what data they wish to retrieve or mutate on a server, leading to fewer round trips and reduced response sizes. Although interest in GraphQL is on the rise, with increasing adoption at major organizations, little is known about what GraphQL interfaces look like in practice. This lack of knowledge makes it hard for providers to understand what practices promote idiomatic, easy-to-use APIs, and what pitfalls to avoid.
To address this gap, we study the design of GraphQL interfaces in practice by analyzing their schemas – the descriptions of their exposed data types and the possible operations on the underlying data. We base our study on two novel corpuses of GraphQL schemas, one of 16 commercial GraphQL schemas and the other of 8,399 GraphQL schemas mined from GitHub projects. We make available to other researchers those schemas mined from GitHub whose licenses permit redistribution. We also make available the scripts to mine the whole corpus. Using the two corpuses, we characterize the size of schemas and their use of GraphQL features and assess the use of both prescribed and organic naming conventions. We also report that a majority of APIs are susceptible to denial of service through complex queries, posing real security risks previously discussed only in theory. We also assess ways in which GraphQL APIs attempt to address these concerns.
This is a preview of subscription content, log in via an institution.
Buying options
Tax calculation will be finalised at checkout
Purchases are for personal use only
Learn about institutional subscriptionsNotes
- 1.
We anonymized the returned names.
- 2.
We submitted a pull request adding several public GraphQL APIs that were missing from the APIs.guru list, but that we found using web searches. The APIs.guru maintainers accepted the pull request and we included those schemas in this analysis.
- 3.
- 4.
If multiple possible definitions were found, we broke ties under the assumption that developers will use the directory hierarchy to place related files close to each other.
- 5.
We collected data in November 2018 using the same methodology, and found 5,345 unique schemas, 701 of which resulted from merging. This reflects a growth of \(57\%\) in half a year.
- 6.
Subscriptions permit clients to register for continuous updates on data.
- 7.
For simplicity, we tested for camelCase and PascalCase names using only the first letter. A more sophisticated dictionary-based analysis is a possible extension.
- 8.
These conventions are “organic” in the sense that they are emerging naturally without apparent central direction. There could, however, be some hidden form of direction, e.g. many projects influenced by the same team or corporation.
- 9.
- 10.
In Table 3, we use the slightly relaxed notion \(O(n \times D^K)\).
- 11.
In GraphQL the first field is always query, and cannot be a list type.
References
APIs-guru/graphql-apis: A collective list of public GraphQL APIs. https://github.com/APIs-guru/graphql-apis
GraphiQL: An in-browser IDE for exploring GraphQL. https://github.com/graphql/graphiql
GraphQL Faker. https://github.com/APIs-guru/graphql-faker
GraphQL Style conventions. https://www.apollographql.com/docs/apollo-server/essentials/schema.html#style
Introduction to GraphQL. https://graphql.org/learn/
JavaScript reference implementation for GraphQL. https://github.com/graphql/graphql-js
Pagination. http://graphql.github.io/learn/pagination/
Schemas and Types. https://graphql.org/learn/schema
Who’s using GraphQL? http://graphql.org/users
Introducing Yelp’s Local Graph (2017). https://engineeringblog.yelp.com/2017/05/introducing-yelps-local-graph.html
React, Relay and GraphQL: Under the Hood of The Times Website Redesign (2017). https://open.nytimes.com/react-relay-and-graphql-under-the-hood-of-the-times-website-redesign-22fb62ea9764
GitHub GraphQL API v4 (2019). https://developer.github.com/v4/
GraphQL and Shopify (2019). https://help.shopify.com/en/api/custom-storefronts/storefront-api/graphql/
GraphQL Current Working Draft: Schema (2019). https://facebook.github.io/graphql/draft/#sec-Executable-Definitions
GraphQL Current Working Draft: Schema (2019). https://facebook.github.io/graphql/draft/#sec-Schema
Brito, G., Mombach, T., Valente, M.T.: Migrating to GraphQL: a practical assessment. In: 2019 IEEE 26th International Conference on Software Analysis, Evolution and Reengineering (SANER), pp. 140–150. IEEE (2019)
Facebook Inc.: GraphQL. Working Draft, June 2018. https://facebook.github.io/graphql/
Gamez-Diaz, A., Fernandez, P., Ruiz-Cortes, A.: An analysis of RESTful APIs offerings in the industry. In: Maximilien, M., Vallecillo, A., Wang, J., Oriol, M. (eds.) ICSOC 2017. LNCS, vol. 10601, pp. 589–604. Springer, Cham (2017). https://doi.org/10.1007/978-3-319-69035-3_43
Hartig, O., Pérez, J.: An initial analysis of Facebook’s GraphQL language. In: CEUR Workshop Proceedings (2017)
Hartig, O., Pérez, J.: Semantics and complexity of GraphQL. In: Conference on World Wide Web (WWW) (2018)
Kim, Y.W., Consens, M.P., Hartig, O.: An empirical analysis of GraphQL API schemas in open code repositories and package registries. In: Proceedings of the 13th Alberto Mendelzon International Workshop on Foundations of Data Management (AMW), June 2019
Palma, F., Gonzalez-Huerta, J., Moha, N., Guéhéneuc, Y.-G., Tremblay, G.: Are RESTful APIs well-designed? Detection of their linguistic (Anti)Patterns. In: Barros, A., Grigori, D., Narendra, N.C., Dam, H.K. (eds.) ICSOC 2015. LNCS, vol. 9435, pp. 171–187. Springer, Heidelberg (2015). https://doi.org/10.1007/978-3-662-48616-0_11
Petrillo, F., Merle, P., Moha, N., Guéhéneuc, Y.-G.: Are REST APIs for cloud computing well-designed? An exploratory study. In: Sheng, Q.Z., Stroulia, E., Tata, S., Bhiri, S. (eds.) ICSOC 2016. LNCS, vol. 9936, pp. 157–170. Springer, Cham (2016). https://doi.org/10.1007/978-3-319-46295-0_10
Rinquin, A.: Avoiding n+1 requests in GraphQL, including within subscriptions
Stoiber, M.: Securing your GraphQL API from malicious queries
Vargas, D.M., et al.: Deviation testing: a test case generation technique for GraphQL APIs (2018)
Vázquez-Ingelmo, A., Cruz-Benito, J., García-Peñalvo, F.J.: Improving the OEEU’s data-driven technological ecosystem’s interoperability with GraphQL. In: Proceedings of the 5th International Conference on Technological Ecosystems for Enhancing Multiculturality - TEEM 2017, pp. 1–8 (2017)
Vogel, M., Weber, S., Zirpins, C.: Experiences on migrating RESTful web services to GraphQL. In: Braubach, L., et al. (eds.) ICSOC 2017. LNCS, vol. 10797, pp. 283–295. Springer, Cham (2018). https://doi.org/10.1007/978-3-319-91764-1_23
Wittern, E., Cha, A., Davis, J.C., Baudart, G., Mandel, L.: GraphQL schema collector. https://doi.org/10.5281/zenodo.3352421, accessible at https://github.com/ErikWittern/graphql-schema-collector
Wittern, E., Cha, A., Davis, J.C., Baudart, G., Mandel, L.: GraphQL Schemas. https://doi.org/10.5281/zenodo.3352419, accessible at https://github.com/ErikWittern/graphql-schemas
Wittern, E., Cha, A., Laredo, J.A.: Generating GraphQL-Wrappers for REST(-like) APIs. In: Mikkonen, T., Klamma, R., Hernández, J. (eds.) ICWE 2018. LNCS, vol. 10845, pp. 65–83. Springer, Cham (2018). https://doi.org/10.1007/978-3-319-91662-0_5
Acknowledgments
We are grateful to A. Kazerouni and B. Pirelli for their feedback on the manuscript, and to O. Hartig for a helpful discussion.
Author information
Authors and Affiliations
Corresponding author
Editor information
Editors and Affiliations
Rights and permissions
Copyright information
© 2019 Springer Nature Switzerland AG
About this paper
Cite this paper
Wittern, E., Cha, A., Davis, J.C., Baudart, G., Mandel, L. (2019). An Empirical Study of GraphQL Schemas. In: Yangui, S., Bouassida Rodriguez, I., Drira, K., Tari, Z. (eds) Service-Oriented Computing. ICSOC 2019. Lecture Notes in Computer Science(), vol 11895. Springer, Cham. https://doi.org/10.1007/978-3-030-33702-5_1
Download citation
DOI: https://doi.org/10.1007/978-3-030-33702-5_1
Published:
Publisher Name: Springer, Cham
Print ISBN: 978-3-030-33701-8
Online ISBN: 978-3-030-33702-5
eBook Packages: Computer ScienceComputer Science (R0)