Do you use Yelp, Shopify, Coursera, or GitHub? If so, you have consumed a GraphQL API! These are just a few of the companies that adopted GraphQL as their data communication solution.

The first part of this book answers the why, what, and how questions about GraphQL. The word GraphQL can mean different things to different people, but it is fundamentally a “language” that API consumers can use to ask for data. This part will get you comfortable with the fundamentals of that language.

In chapter 1, you’ll learn what exactly GraphQL is, what problems it solves, and what problems it introduces. You’ll explore the design concepts behind it and how it is different from the alternatives, like REST APIs.

Chapter 2 explores GraphQL’s feature-rich interactive playground. This playground takes advantage of GraphQL’s introspective power, which you can use to explore what you can do with GraphQL and to write and test GraphQL requests. You’ll use this playground to explore examples of GraphQL queries and mutations. You’ll learn about the fundamental parts of a GraphQL request, and you’ll test practical examples from the GitHub GraphQL API.

Chapter 3 introduces you to the many built-in features of the GraphQL language that let you customize and organize data requests and responses. You’ll learn about fields and arguments, aliases, directives, fragments, interfaces, and unions.

Necessity is the mother of invention. The product that inspired the creation of GraphQL was invented at Facebook because the company needed to solve many technical issues with its mobile application. However, I think GraphQL became so popular so fast not because it solves technical problems but rather because it solves communication problems.

Communication is hard. Improving our communication skills makes our lives better on many levels. Similarly, improving the communication between the different parts of a software application makes that application easier to understand, develop, maintain, and scale.

That’s why I think GraphQL is a game changer. It changes the game of how the different “ends” of a software application (frontend and backend) communicate with each other. It gives them equal power, makes them independent of each other, decouples their communication process from its underlying technical transport channel, and introduces a rich new language in a place where the common previously spoken language was limited to a few words.

GraphQL powers many applications at Facebook today, including the main web application at facebook.com, the Facebook mobile application, and Instagram. Developers’ interest in GraphQL is very clear, and GraphQL’s adoption is growing fast. Besides Facebook, GraphQL is used in many other major web and mobile applications like GitHub, Airbnb, Yelp, Pinterest, Twitter, New York Times, Coursera, and Shopify. Given that GraphQL is a young technology, this is an impressive list.

In this first chapter, let’s learn what GraphQL is, what problems it solves, and what problems it introduces.

The word graph in GraphQL comes from the fact that the best way to represent data in the real world is with a graph-like data structure. If you analyze any data model, big or small, you’ll always find it to be a graph of objects with many relations between them.

That was the first “Aha!” moment for me when I started learning about GraphQL. Why think of data in terms of resources (in URLs) or tables when you can think of it naturally as a graph?

Note that the graph in GraphQL does not mean that GraphQL can only be used with a “graph database.” You can have a document database (like MongoDB) or a relational database (like PostgreSQL) and use GraphQL to represent your API data in a graph-like structure.

The QL in GraphQL might be a bit confusing, though. Yes, GraphQL is a query language for data APIs, but that’s only from the perspective of the frontend consumer of those data APIs. GraphQL is also a runtime layer that needs to be implemented on the backend, and that layer is what makes the frontend consumer able to use the new language.

The GraphQL language is designed to be declarative, flexible, and efficient. Developers of data API consumers (like mobile and web applications) can use that language to request the data they need in a language close to how they think about data in their heads instead of a language related to how the data is stored or how data relations are implemented.

On the backend, a GraphQL-based stack needs a runtime. That runtime provides a structure for servers to describe the data to be exposed in their APIs. This structure is what we call a schema in the GraphQL world. An API consumer can then use the GraphQL language to construct a text request representing their exact data needs. The client sends that text request to the API service through a transport channel (for example, HTTPS). The GraphQL runtime layer accepts the text request, communicates with other services in the backend stack to put together a suitable data response, and then sends that data back to the consumer in a format like JSON. Figure 1.1 summarizes the dynamics of this communication.

In general, an API is an interface that enables communication between multiple components in an application. For example, an API can enable the communication that needs to happen between a web client and a database server. The client tells the server what data it needs, and the server fulfills the client’s requirement with objects representing the data the client asked for (figure 1.2).

There are different types of APIs, and every big application needs them. For GraphQL, we are specifically talking about the API type used to read and modify data, which is usually referred to as a data API.

GraphQL is one option out of many that can be used to provide applications with programmable interfaces to read and modify the data the applications need from data services. Other options include REST, SOAP, XML, and even SQL itself.

SQL (Structured Query Language) might be directly compared to GraphQL because QL is in both names, after all. Both SQL and GraphQL provide a language to query data schemas. They can both be used to read and modify data. For example, if we have a table of data about a company’s employees, the following is an example SQL statement to read data about the employees in one department.

SELECT id, first_name, last_name, email, birth_date, hire_date FROM employees WHERE department = 'ENGINEERING'

Here is another example SQL statement that inserts data for a new employee.

INSERT INTO employees (first_name, last_name, email, birth_date, hire_date) VALUES ('Jane', 'Doe', '[email protected]', '01/01/1990', '01/01/2020')

You can use SQL to communicate data operations as we did i...