What is GraphQL?

If you are a frontend web developer you have probably heard of GraphQL or maybe you have even used it, but what is it? GraphQL is a query language for APIs that allows you to write queries that define the data you receive. No more emailing the backend team to update an endpoint for your application. The client developer defines the data returned in the request.

What is a GraphQL Server/API?

A GraphQL server is a server-side implementation of the GraphQL spec. In other words, a GraphQL server exposes your data as a GraphQL API that your client applications can query for data. These clients could be a single page application, a CMS like Drupal, a mobile app, or almost anything. For example, say you have a MySQL database and you want to expose the content to a React application. You could create a GraphQL server that will allow our React application to query the database indirectly through the GraphQL server.

Why would you consider a GraphQL API?

1. You need an API for your applications

At Mediacurrent, we have been building decoupled static web sites using GatsbyJS. But sometimes we also need some components with dynamic data. You need an API for that and our front-end team was already using GraphQL in Gatsby. Or maybe you might develop a mobile app and need a reliable and fast way to get data from your legacy database. You can use GraphQL to expose only the data you need for your new app but at the same time give your client app developers the ability to control what data they get back from the API.

2. You need data normalization

For our purposes as developers data normalization is simply the process of structuring our data to remove redundancy and create relationships between our data. Data normalization is something database designers think about but developers and software architects should consider as well.

One of the biggest mistakes I’ve seen in my years building web applications is the pattern of including too much business logic in application components. These days, it is not unusual to require data from multiple applications, public REST APIs as well as databases. There is often duplication across these systems and the relationships are rarely clear to the development team. Creating components that require data from multiple systems can be a challenging task. Not only do you have to make multiple queries to retrieve the data, but you also need to combine it in your component. It’s a good pattern to normalize the data outside of your components so that your client application’s components can be as simple and easy to maintain as possible. This is an area where GraphQL shines. You define your data’s types and the relationships between your data in a schema. This is what allows your client applications to query data from multiple data sources in a single request.

3. You love your client application developers

A well-built GraphQL server will avoid these issues that are common with REST APIs.

• Over-fetching - receiving more data than you need.
• Under-fetching - not receiving all the data you need.
• Dependent requests - requiring a series of requests to get the data you need.
• Multiple round trips - needing to wait for multiple requests to resolve before you can continue.

Over-fetching

In a perfect world, we would only fetch the data we need. If you have ever worked with a REST API you will likely know what I mean here. Your client application developers may only need a user’s name but it is likely that when they request the name using the REST endpoint they will get much more data back from the API. GraphQL allows the client to specify the data returned in the request. This means a smaller payload delivered over the web which will only help your app be more performant.

Under-fetching, dependent requests, and multiple round trips

​

Another scenario is under-fetching. If you need a user’s name and the last three projects they were active on, you probably need to make two HTTP requests to your REST API. With GraphQL relationships, you can get this data back in a single request. No more callbacks and waiting on multiple endpoints to resolve. Get all your data in one request. Now you are avoiding multiple requests, dependent requests, and multiple round trips to get the data for your app’s components.

​

GraphQL single request to multiple data sources.

Self documenting

The type based schema that GraphQL provides creates the structure to build powerful tools like Graphiql, an in-browser IDE for exploring GraphQL.

This schema also allows for what I would call a self documenting API. GraphQL playground is an example of the power of the GraphQL schema. It takes this schema and creates documentation as well as an IDE like Graphiql. When you update your schema, your documentation is automatically updated as well as the IDE. That’s a huge win!