Categories
Uncategorized

Notes on REST and GraphQL

Written by Elina Kettunen (UH)

The RESTful web API has been the standard API design architecture, yet during the recent years APIs based on GraphQL Schema Definition Language have gained popularity. In this post the idea is to look into both advantages and disadvantages of REST- and GraphQL-based web APIs. The findings from scientific literature and blog posts are summarised in Tables 1 and 2. 

GraphQL [1] was published by Facebook in 2015, and its key characteristics are support for a hierarchical data model and client-specific queries. The hierarchical data model can reduce the number of endpoints the API clients need to access and the clients can ask only for the data they need [2]. With REST APIs, common problems have been either over-or under-fetching of data; sometimes the client only wishes to show a small part of the available data but the API endpoint provides too much information in the JSON file, and sometimes the client is required to access multiple endpoints to fetch all desired data. Using GraphQL does not necessarily lead to the reduction in the number of queries the API clients need to perform, but it has been shown that in some cases GraphQL can reduce the size of returned JSON documents by over 90% (number of fields and byte size) compared to REST-based APIs [2].

In one study, implementing GraphQL API queries was found to be easier to learn than implementing queries to REST APIs, especially if the query contained multiple parameters [3]. However, implementing a GraphQL server requires certain components such as a GraphQL execution unit, schema and resolvers on the API layer [4], which add complexity and might make using GraphQL overkill for simple applications [5]. Also, with REST APIs, using HTTP caching is easy, but since with GraphQL the idea is to provide a single endpoint for API queries, implementing caching requires extra effort from the developer [2, 5]. 

GraphQL is strongly typed, which means the clients must adhere to data type definitions when making queries, adding to the security of GraphQL [2]. With REST APIs, handling different call types and returned data formats is relatively easy, but file uploading was initially not supported by GraphQL and support for file upload requires installing a library [6]. Since client applications are able to see all fields in GraphQL, information hiding is not well supported [2].

Large, complex nested queries are a potential performance and security problem for GraphQL servers, since processing large queries requires considerable effort and may lead to denial of service if the server cannot cope with the requests. Limiting the query complexity and depth is therefore necessary [7]. 

As a still emerging technology, GraphQL does not have as much tool support as REST APIs. The lack of monitoring tools has been mentioned in one blog post [8]. GraphQL has also lacked means for integrating multiple interfaces that are important in distributed systems. A solution to this problem is to use GraphQL Federations, which are common interfaces used on top of existing GraphQL web service interfaces. Besides an existing solution (Apollo Federation [9]) researchers have also proposed a novel framework to address the multiple interface integration problem [10]. 

REST APIs are generally considered simple and inexpensive with good interoperability, flexibility, scalability and robustness. GraphQL provides great flexibility on the frontend as changes in data usage usually need not to affect the server. GraphQL and REST do not need to be alternatives to each other as they can be used in parallel. GraphQL is well suited for example API gateways [4]. There are several GraphQL engines that support major programming languages and different query planning tools can translate GraphQL queries into other query languages [11]. Also, deprecating fields is easy and adding new fields to a type does not lead to breaking changes in GraphQL APIs, which makes versioning easier [2]. With GraphQL, API developers can avoid over- and under-fetching issues, and gain performance benefits by reducing the overhead from transferring large JSON files.

Table 1. Advantages and disadvantages of REST API design architecture.

Table 2. Advantages and disadvantages of GraphQL design API architecture.

References

[1] https://graphql.org/

[2] Brito, G., Mombach, T. & Valente, M.T. 2019, “Migrating to GraphQL: A Practical Assessment”, SANER 2019 – Proceedings of the 2019 IEEE 26th International Conference on Software Analysis, Evolution, and Reengineering, pp. 140-150. 

[3] Brito, G. & Valente, M.T. 2020, “REST vs GraphQL: A controlled experiment”, Proceedings – IEEE 17th International Conference on Software Architecture, ICSA 2020, pp. 81-91. 

[4] Vogel, M., Weber, S. & Zirpins, C. 2018, Experiences on Migrating RESTful Web Services to GraphQL. In: International Conference on Service-Oriented Computing. Springer, Cham, 2017. p. 283-295.

[5] https://medium.com/@back4apps/graphql-vs-rest-62a3d6c2021d

[6] https://levelup.gitconnected.com/how-to-add-file-upload-to-your-graphql-api-34d51e341f38

[7] Wittern, E., Cha, A., Davis, J.C., Baudart, G. & Mandel, L. 2019, An Empirical Study of GraphQL Schemas. In: International Conference on Service-Oriented Computing. Springer, Cham, 2019. p. 3-19.

[8] https://www.moesif.com/blog/technical/graphql/REST-vs-GraphQL-APIs-the-good-the-bad-the-ugly/

[9] https://www.apollographql.com/docs/federation/