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!

You can try out a demo of the GraphQL Playground on graphqlbin.com.

4. GraphQL can replace your legacy REST API

It can be challenging to maintain versions of a REST API. Requirements change. You need to add new fields or maybe you want to delete fields from your database. Due to the requirements for backward compatibility your API has to continue supporting these old requirements. Maybe you have an old Android mobile app that relies on your REST endpoints. Maybe you have a Salesforce integration that you don’t have time to update. Most organizations can’t update all their applications at once so you can’t just turn off your old REST API. A GraphQL server can act as a middleware between your old REST API and your new applications. Then as you update your other client apps that use the REST API’s you can update them to work with your new GraphQL API. Once all of your clients are no longer using the REST endpoints you can replace the REST API fully with the GraphQL API.

5. You’re tired of maintaining old versions of your REST API

GraphQL has the @deprecated annotation that you can add to your schema to let clients know that a field should no longer be used. This is much easier to maintain than multiple versions of a REST API.

Which server should you use?

Check out GraphQL.org’s list of servers. There are projects in C# / .NET, Clojure, Elixir, Erlang, Go, Groovy, Java, JavaScript, PHP, Python, Scala, and even Ruby. My choice is the Apollo Server project. It has great documentation and provides a self documenting API for your team that is enjoyable to use. If you use Drupal there is the Graphql module that adds a GraphQL API to your site.

I hope I’ve sparked your interest in GraphQL and building a GraphQL server API. At Mediacurrent, we have seen how powerful this tool can be for solving complex application and data problems and we’d love to talk with you about it. Hit us up in the comments.