Facebook started developing GraphQL in 2012 and released it in 2015. Since 2018, the Linux Foundation is responsible for the project. GraphQL’s purpose is to provide a query language for data fetching and manipulation. It is not exactly SQL, and not REST, either. It is somewhere in between, allowing developers to query, mutate and organize data in an intuitive and safe way.

Alternatives: REST

To understand what is GraphQL, you should first understand what GraphSQL is not. Firstly, it is not REST. REST stands for REpresentational State Transfer and it has been an industry standard for API development for many years. REST lets you perform client/server communication with a subset of HTTP requests. In addition, it provides rules and general philosophy of how to structure and name these requests. Most often, JSON (JavaScript Object Notation) is used to send data.

So, what is wrong with REST? A lot of things. One of the main reasons is that there is no strong contractual agreement between server and client. That means no guarantees on the type or structure of data you are about to receive. Also, ambiguity among different HTTP status codes. For example, should you return a 200 because the request was successful, or a 201 because an item was created?

SOAP

SOAP (Simple Object Access Protocol) was commonly used before REST. Unlike REST, SOAP is a standardized protocol, developed by Microsoft and approved by W3C. It used XML notation to send and receive data. SOAP was later extended and applied to support remote procedure calls. It also was not limited to HTTP. SOAP messages could be sent over other protocols, such as SMTP, and directly over TCP.

While being very robust, SOAP was critiqued for being too verbose and slow. That is why developers switched to more low-level protocols, such as REST.

SQL

SQL stands for the structured query language. It is mainly used in the context of databases. While it has nothing to do with APIs and client/server communication, it is very worth noting as it has a lot in common with GraphQL.

Both of them provide contractual agreements and a well-defined specification. The primary objective of both SQL and GraphQL is to query and manipulate data. The difference is that SQL is designed to work with relational databases, while GraphQL was developed with NoSQL solutions in mind. GraphQL also specifies how two parties should communicate over the network, while SQL makes no such assumptions.

You could also say that SQL has a more rich set of features compared to GraphQL. It supports more operations on data, as well as functions and other aspects, usually reserved for programming languages.

Core concepts

With the alternatives out of our way, we can dive into GraphQL. It is important to understand some core concepts of GraphQL to be able to effectively use it.

Schema

The foundation of a GraphQL API is a schema. A schema is a definition of all possible data the API can handle and the types of this data. It usually resides on the server-side, and all incoming queries are first validated against the schema.

Field

As the official GraphQL docs put it, “[GraphQL] is basically about selecting fields on objects”. A field is the most basic unit of data you can request from the API. It also has to be a scalar, meaning no relationships or complexities.

Implementation

Implementation in GraphQL is like inheritance in OOP. It lets you define some common fields that are going to be shared across different objects.

Connection

Connection is where the Graph in GraphQL comes from. It lets you interconnect different objects between each other, very much like nodes in a graph. These connections let you query multiple objects in one call, wherein REST you would need multiple calls.

Examples

Now let’s look at some examples of GraphQL in action. We begin by defining a type. It is written in SDL (Schema Definition Language):

You can see its name is Car and it has fields make, year and turbocharged. Each field has a specific type. In addition, the exclamation mark means that the field is required.

But to really explore the ideas of GraphQL, we need to introduce some relationships. Let us define another type and tie it to the Car:

You can see that Car now has a reference to Person via the owner field, and Person keeps a list of Car in the cars field.

Queries

To be able to query cars and persons, we now need to define some Queries:

You can see we have defined 3 queries. allCars accepts no arguments and returns a list of Car. carsByMake takes a string and filters cars by make. Lastly, allPersons will return a list of Person.

Now we can send queries to the API and get results like this:

Pass variables to queries:

Mutations

Querying data is good, but we also need a way to create the data in the first place. GraphQL uses mutations to do this. You define mutations much like queries:

This is an example of a mutation that will accept data and create a Car object. You can call it like this:

Implementations

GraphQL by itself is not a library or a framework: it is merely a specification. Many libraries in different languages implement this specification, allowing you to build your API with GraphQL support. Here are some of them:

• JavaScipt: graphql and express-graphql
• Java: graphql-java
• Python: graphene

For frontend, Apollo library is most common.

Pros and Cons

So, why should you use GraphQL and why avoid it? Here are some reasons in favor of GraphQL:

• Strong contractual agreement – you no longer have to guess what kind of data server is going to send you. With GraphQL, you get exactly what you asked for
• Fewer requests – GraphQL can do things with fewer requests, compared to REST or SOAP
• Intuitive – GraphQL is much more intuitive and easy to use rather than REST or SOAP.

But GraphQL is not perfect. Here are the cons of GraphQL:

• Overhead – GraphQL comes with quite a bit of setup, and this may not be efficient for small projects
• Age – GraphQL is much younger than REST or SOAP, meaning it has less learning materials and best practices

I hope now you have a solid understanding of what GraphQL is and what problems does it solve. Thank you for reading and let me know what you think about GraphQL in the comments!