Common GraphQL misconceptions demystified

Now that GraphQL has become the de-facto buzzword in web development circles we should take a moment to understand exactly what it is, and most importantly, what it isn’t.

What is GraphQL?

GraphQL is a query language designed as a contract to be used between an API consumer and a backend service. It is a Domain-specific Language that allows an API consumer access to query and manipulate highly relational data objects exposed by an API (traditionally web based).

This schema describes a couple of related objects, their properties as well as their relationship. This syntax is called SDL or Schema Definition Language and is an extension of GraphQL used to describe objects and their relationships. Here are a couple examples of how I would query this data.

This would return a JSON object containing a list of vehicles and manufacturers, as well as the specific properties I have requested on them. GraphQL gets more exciting when we reveal the relational capabilities that it was designed for.

This would return a list of vehicles with the properties I prescribed, as well as a nested object of the manufacturer that the vehicle belongs to! Now you can start to imagine just how powerful this can be.

What problem does GraphQL solve?

GraphQL was designed by facebook to provide a better solution to build client application on top of highly complex, highly relational data spread across a network of complex services. In short, GraphQL was invented to solve problems of scale in multiple directions, breadth (data that’s highly relational) depth (data that is highly distributed) and complexity (specification and communication requirements between development teams).

By allowing the client to more specifically define what data it needs, it can drastically decrease the amount of data exchanged over the network (both internally, and to the client over the internet). It also explicitly defines what data can be created and changed and how; in the GraphQL universe, called mutations.

Since GraphQL is simply a language used as a contract, it describes exactly what backend and frontend teams need to implement, helping to solve the problem of the depth of detail and communication required between teams implementing these solutions.

Where have I seen this before??

These problems are not new, nor are the solutions created to solve them. One of the things that deeply fascinates me about the field of Software Development is that we get to witness evolution at a very rapid pace right out in the open (thank you open source!!)

Yahoo Query Language or YQL was recently put to rest was introduced way back in 2009. YQL, as you can probably surmise, was very similar to SQL. It was meant to be used over an API that connected Yahoo!’s many data services and allowed clients to request specific columns as well as relational data.

Salesforce Object Query Language or SOQL is a proprietary Object Query Language created by Salesforce to allow CRM developers access to nested and relational data which also looks a little more like traditional SQL.

Falcor is another example of (perhaps) convergent evolution that is described as a solution that “allows you to model all your backend data as a single Virtual JSON object on your Node server.” It solves the same issue by providing a schema document (smartly implemented in JSON) that describes the data that is available in the API. It also provides a simple protocol for how to access that data over a REST-like interface very much like GraphQL.

All of these solutions solve the same problem SQL did way back in 1974 as a way to access data in an easy to understand format from complex and different database systems.

What is GraphQL NOT?

The most common misconception about GraphQL is that it is a direct replacement for REST. This isn’t quite correct because the two concepts are completely different. REST is a software architecture style meant to describe how a client interacts with a server over HTTP whereas GraphQL uses a REST-like interface to implement a language describing how to get data from a (usually complex) service. This is like trying to compare a BBQ Grill (REST) with a recipe for Grilled Salmon (GraphQL).

Isn’t GraphQL the best option for any modern web based API?

• Not necessarily. Where GraphQL shines is when you are dealing with highly relational data, and distributed backend systems. The power is that it provides an opinionated contract that both backend and frontend teams can agree on and use to communicate how to interact with complex data objects and relationships. Or if you are working alone, or in small teams, a way to separate the concerns of the backend from the front and allow parallel, but independent development to take place.

Isn’t GraphQL a way to prevent me from having to get my hands dirty writing SQL and interacting with ugly annoying databases?

• In its raw form GraphQL looks like a replacement for SQL or other database CRUD interfaces, but it isn’t. Instead it is a layer of complexity on top of those interfaces. Powerful tooling has made GraphQL feel like a replacement to writing SQL or directly interacting with databases, but it is a layer on top of those tools. I strongly advise understanding what is going on under the hood with these types of tools to ensure that you can architect and debug the underlying technology efficiently.

Do I need to learn GraphQL right now to be an efficient modern web developer?

• Probably not. GraphQL was publicly released in 2015 making it quite a bit less mature than pure REST 22 years old, and SOAP 25 years old which both have the lion’s share of public API implementations. It is, however, good to understand what exactly it is, and what problems it solves in case you are tackling a new project where it could come in handy!

Give me the TL:DR!

GraphQL is not a direct replacement for REST but instead one of the latest in the evolution of Domain-Specific Languages designed to make problems of scale (especially relational) transparent to developers making the complex task of interfacing with increasingly distributed systems simple.