You have most likely heard of it - GraphQL. It may very well be the reason you are reading this right now. So, what is GraphQL? How does it compare to REST? How will it impact the business? What are some great resources to get started?
GraphQL is a technology built by Facebook to replace REST APIs. The reason it replaces REST is to solve a specific set of problems. The problems that GraphQL solves over REST are as follows. Large enterprises have many REST APIs. These are APIs serving many platforms. These applications tend to serve optimized API models depending on the client platform.
There are two examples of RESTful APIs existing at scale in the wild. The examples come from two tech giants - Facebook and Netflix. One solved the problem with a platform tool, another solved the problem with GraphQL. Both of these companies are excellent cases as their products span many platforms.
The Netflix approach to the problem statement is a service that orchestrates many REST APIs. This service is Zuul.
Facebook went a different route. They transitioned from many REST API models via an API Gateway to a new standard in network communications - GraphQL. Here is the gist of what they were after:
GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools. - graphql.org
What is the biggest contrast between REST APIs and GraphQL? It is the representation of the data and how it flows through the system. This is observed in the following use case of a mobile application consuming service resources. Here is the foundation of the example: given a resource that represents a user, the mobile application needs to display the first name of that user resource.
In the REST use case, there is an available resource API at a GET route for reading the data via HTTPS. This GET response would return all fields of the requested resource to the mobile application. The mobile application would then render a screen, displaying some of the data returned by the REST API. This view data would be filtered and formatted by the mobile application.
In the GraphQL use case, there is one available endpoint, served over either HTTPS or some other OSI Level 7 layer. The mobile application request would contain information defining specific data it wanted returned – the query. The GraphQL server would format and filter the data in accordance with the client query request to return as a best fit response. The mobile application would then use all the data it requested to render to the screen.
After looking at those two use cases there are several pointed differences between REST and GraphQL. First, REST is served via HTTP/HTTPS but GraphQL does not couple itself to a specific application protocol. Second, the responsibility of filtering and formatting data shifts from a myriad of client applications – which may even use the same formatting rules – to the resource server. Finally, REST returns data as a state of the resource, GraphQL returns the data as a queried graph.
Also noted are several performance issues in the REST use case. The mobile application only needs to display the first name of the user. However, the mobile application will receive all the information about the specific user. This results in wasted network bytes, increased response time, and backend processing of all data despite not necessarily being needed. While negligible for small resources, the performance impact becomes noticeable as the application and data scales in size.
The biggest question that comes after the technical arguments for using something is “What value does this bring to the business?”. While not all situations are the same, there are several common use cases where the business value is noticeable to the bottom line.
These scenarios are cloud hosted environments, reduction in API management, reduced code complexity, and a better API consumer experience.
GraphQL can reduce the cost of hosting in a cloud service such as AWS or Azure. The direct impact GraphQL will have is on the amount of network bytes sent out of your cloud environment. This is accomplished by executing fewer and succinct requests via a GraphQL query request and receiving smaller responses. See the mobile application use case discussed before. Instead of paying for every egress byte of data that will not be used, only pay for the egress bytes that will be used. At scale this can reduce network costs.
Another cost factor all projects need to consider is maintenance and management of APIs and the services that define them. With GraphQL, there is typically only one API, the GraphQL endpoint. This means an easier to discover and reason about API design. This also removes the need to have additional services such as Zuul operating. This causes a reduction in compute resources. Which, if in a cloud environment, this means less operational expenses and consumed resources.
By reducing the need to create optimized APIs for specific platform clients, there is less code complexity in deploying GraphQL services. In the previous case of the mobile application, a new REST API could have been deployed that was specific to the mobile application. However, there would still be the issue of having a max payload size equal to the largest payload size to meet the functionality of all mobile application features. The other cost factor is the deployment and maintenance of either a new service or another API Gateway configuration that needs to be tested. With GraphQL, only one schema is defined, providing the needs of all clients.
The final note of how GraphQL has business value is the ability to provide a better API consumer experience. This has the most impact on a business built around a platform instead of a product. GraphQL prides itself in being a self-discoverable, self-documenting API by nature. Most of the work for documentation is provided by GraphQL itself. A best practice of GraphQL is to focus on evolving with the needs of the client, rather than the representation of the resources. This provides a better API consumer experience.
Looking at some of the cost savings seen in network, compute, and maintenance, there is evidence that GraphQL APIs can introduce financial and streamlined product development business value. Finally, if a business model is built around another revenue stream via APIs, it can provide a better customer experience.
The arguments for GraphQL are strong. After discovering what it is, using it can provide many benefits to developers and the business. The natural next step is getting started! Below is an amazing list of all the tools I have used for several projects (enterprise, single applications, and more) to create the best GraphQL experience and speed up development.