At API Days Paris 2016, Arnaud Lauret discussed GraphQL vs RESTful HTTP API’s, outlining their strengths and weaknesses. He concluded that deciding which one to adopt is context dependant, and that are many trade-offs between the two.
At API Days Paris, Arnaud Lauret discussed the strengths and weaknesses of GraphQL and RESTful HTTP API’s. He concluded that deciding which one to adopt is context dependent, and that are many trade-offs between the two.
GraphQL is a query language for API’s. It was originally written and the open sourced by Facebook, and can be seen as an alternative to REST. When comparing the two, Lauret, API Architect at AXA Banque, gave some key takeaways as:
Lauret cites the main advantage of GraphQL to be that it’s WYSIWYG model. In other words, the structure of a query result will map exactly to the structure of the query itself, leading to consumers which are less likely to error when trying to unmarshal responses.
He also explains how the GraphQL model leads to fewer network hops. With a RESTful HTTP API, resources and sub-resources can live at different endpoints, requiring multiple requests to retrieve all the desired data. With GraphQL, they can be retrieved with a single query. In fact, it’s possible to query every single resource within the system at once.
Although he believes this model can be powerful, Lauret explains how a single endpoint approach can lead to a loss of consistency and predictability. When compared to a RESTful HTTP API’s, one of the most apparent losses is the proper use of HTTP verbs. For example in RESTful HTTP, when a consumer sends a DELETE request to a resource, they know the operation is safe and idempotent, and they also know that it was intended for resource deletion.
Lauret points out another loss of predictability to be the use of HTTP status codes, something which in RESTful HTTP API’s are both machine and human readable. Examples of this would be retrieving a 404 when unable to find a resource, a 403 when a consumer is unable to access it, and more.
REST also makes use of hypermedia, allowing consumers to discover links and related resources as they traverse the API. This removes the need for things such as link building and gives the client information about resource relations. Lauret explains that as GraphQL purely focuses on data, developers tend to be more dependant on documentation.
Lauret also raises that HTTP RESTful API’s make use of standard HTTP caching, something which is already part of the architecture of the web. With GraphQL, the consumer may have to deal with a custom caching implementation, something which could end up being an extra responsibility that could have been avoided.
Lauret lists a final advantage of GraphQL as it providing a schema, something that can be retrieved at runtime. This can be helpful for clients when trying to determine possible queries. However, Lauret warns that interface description is not documentation and that GraphQL will not necessarily solve your API documentation problems.
To conclude, Lauret believes there is no silver bullet, and it’s just a matter of choosing whatever makes the most sense for the current requirements. He also mentions that due to high-level commonalities, if a user is bad at designing one type of an API, they are likely to be bad at designing any type. The full video can be watched online and is also summed up in a blog post.
