Ruthger Idema

Moving to headless: RESTful vs GraphQL

By Ruthger Idema • 2019-03-16 19:32:04
We live in an era of REST APIs. Whoever builds a web API often chooses blindly to connect it to the outside world with the help of RESTful web services. This is a logical choice since the principles of REST enable both front-end and back-end engineers to develop web applications quickly and intuitively. But next to REST (and SOAP, which I don't see as an alternative) there is a relatively new kid on the block: GraphQL (graph query language). GraphQL is developed in-house by Facebook in 2012 and released in 2015. In this article, I will explain both types and their pro's and con's

 The REST model is a software architecture style for building scalable web services. The model is an extension of the way the web itself works, with the same GET, POST and PUT requests. A RESTful web service returns the requested information using JSON, XML or HTML. This allows back end developers to put web services online without developing a user interface. The front end developer can then receive the web service and can develop a user interface based on an interpretation of this service.
The reason that many programmers follow the RESTful approach is that it is relatively easier to understand because it is very logical. Next, to that, many developers have been working with this method of data delivery for years, making it an easily applicable solution for many types of applications. Most tutorials about API scaffolding are written in favor of REST, which educates new developers to use this type of API.
RESTful web services have a major disadvantage: the API determines exactly which data and format the front-end applications can retrieve. You will find little trouble when you only have to maintain a single application, but if you have an API that is used by multiple front-ends then this will be a problem. Every front-end application will need its own data and must be maintained for all front ends.

This can mean that your front-end applications must make multiple calls to the API to retrieve the desired data. This obviously does not benefit performance. To prevent this, you could build API endpoints that exactly match the data needs of specific front-end applications. However, this has the disadvantage that it ensures tight coupling between the API and your front-end application.
GraphQL is a platform agnostic query language and runtime environment that enables you, just like REST, to connect an application to the outside world. With GraphQL a user, for example, a front-end application can send requests to the backend application. With the help of self-compiled queries, the user can make it clear exactly what he needs from the API. The runtime of GraphQL, which runs in the backend application, translates these queries into functions that can retrieve or modify data. 

While RESTful web services generally offer multiple endpoints for retrieving and changing data, a GraphQL API only has one. This makes it possible to retrieve exactly the data you need with a single request.

With the arrival of Magento 2.3, developers can now also use GraphQL. This functionality ensures that your Magento webshop(s) will be many times faster because less unnecessary data is retrieved. If you run a REST call, for example, GET /V1/products/:sku on a product, the system fetches 100 rows or more. If you only need the description of the product, the GraphQL endpoint only returns the description. Find out more about GraphQL in Magento in the Magento devdocs.

If you are using Laravel 5.x, you can use the rebing/graphql-laravel package. In one of the next chapters of 'moving to headless' I will explain a bit more about this package.

My opinion
GraphQL takes the simplicity and logic of RESTful web services and adds the necessary dose of autonomy and clarity for the API users. Thanks to the flexible, intuitive query language, the simple backend implementation, and the excellent tooling, GraphQL is a great alternative to RESTful web services. In the beginning it might seem intimidating because the conceptual ideas are a bit different, so take your time to get yourself familiar. For small applications, I will still use a RESTful implementation, but as soon as an application is bigger (or starts to grow bigger) I would definitely use GraphQL.