The following is the first few sections of a chapter from The Busy Coder's Guide to Android Development, plus headings for the remaining major sections, to give you an idea about the content of the chapter.


The Role of GraphQL

Why was GraphQL created?

What does GraphQL offer us that alternatives do not?

What are those alternatives, anyway?

GraphQL has garnered a fair bit of attention in its short lifetime, but mostly in the world of Web developers. In the world of mobile app development, though, GraphQL has had a slower adoption curve and a corresponding lower amount of discussion.

In other words: you’ve got questions. That’s understandable.

In this chapter, we will focus on trying to get you answers to those questions, so that you better understand the reasons why you might want to use GraphQL, beyond “my boss told me so”.

However, let’s first focus on another question…

So, What Did We Just Do?

In the preceding chapter, we played around with a Web-based tool called GraphiQL, typed some stuff in, and got some stuff back. To anyone who has used the Internet in the past decade or so, what we did, on the surface, may not seem that exciting.

And, to some extent, GraphQL is not breaking new ground. It is merely a way to describe a request for some data, and a way for sources of data to respond to those requests and structure a response. We have been doing that sort of thing for decades, picking up steam with the advent of client-server as a popular system paradigm in the late 1980’s. There is a decent chance that you were not even born yet.

But let’s think a bit about the nature of what we typed in and the nature of what we got back.

First, let’s look at what we typed in again:

{
  allTrips {
    id
    title
  }
}

GraphQL is all about the fields. allTrips is a field on a particular object, known as the Query, that exposes data that we can read from the server. As it turns out, and as we saw in the generated documentation, allTrips will return data about Trip objects. Trip objects have their own fields, like id, title, and creationTime. When we get the allTrips response, rather than getting all possible fields on the Trip objects, we are saying “only give us the id and title, please”.

Now, let’s compare that with the response:

{
  "data": {
    "allTrips": [
      {
        "id": "2c494055-78bc-430c-9ab7-19817f3fc060",
        "title": "Vacation!"
      },
      {
        "id": "e323fed5-6805-4bcf-8cb6-8b7a5014a9d9",
        "title": "Business Trip"
      }
    ]
  }
}

First, the response is in JSON. That is not a requirement of GraphQL, though it is a common implementation. So, this feels a bit like a REST-style Web service, or perhaps some sort of document database.

However, the specific data we got back was structured to match the data that we requested:

This feature of limiting the breadth of the response to only the fields that we care about is interesting. This is not the sort of thing that you usually see with REST-style Web services, or even things like Java method calls. For example, in Java, we could have something like:

List<Trip> allTrips() {
  // really fun code here
}

However, there, the Trip “is what it is”. We do not tell allTrips() what particular bits of data are of interest.

Instead, this feels a bit more like something that we might do with SQL, to request data from a relational database:

SELECT id, title FROM trips;

GraphQL borrows bits and pieces from a number of existing communication patterns to craft a new one. The key for us is whether this new one is a case of “the whole is greater than the some of its parts”, or whether this new one more resembles the monster created by Dr. Frankenstein (either Victor Frankenstein or Frederick Frankenstein, as you see fit).

What Exactly is GraphQL?

GraphQL is a query language designed to sent to some server, where the server can send back a response based upon the request that was submitted.

Of course, that explanation is a bit broad.

A Specification

The most important thing that GraphQL “is” is a specification.

That specification describes:

Along the way, the specification enforces a few design principles, which we will see shortly.

A Set of Conventions

However, the GraphQL specification is fairly compact. It focuses on syntax and expected results. It does not address a lot of things that one needs to really apply GraphQL in practice.

The biggest one is: how does the request get to the server, and how does the response get back?

When we executed the request using GraphiQL, we used HTTP for those steps. GraphiQL knows:

However, the GraphQL specification does not address this.

On the one hand, this allows for a lot of flexibility and room for experimentation. On the other hand, it does make it a bit difficult for newcomers to understand how to use GraphQL to accomplish something worthwhile.

As with many software ecosystems, conventions take over where specifications leave off. In the case of determining how we send GraphQL and responses between clients and servers, the GraphQL developer documentation describes conventions for serving GraphQL over HTTP.

Other conventions revolve around certain GraphQL-aware products and projects. For example, you will hear about “Relay-compliant servers”, referring here to Facebook’s Relay project, which ties GraphQL to a particular JavaScript framework for creating Web apps.

A Lot of Froth

Whenever you have a new, exciting technology, all sorts of people start offering things around the technology: tools, libraries, consulting, conferences…

Even books!

These each provide possibilities for furthering your use of the technology. However, until enough people have “kicked the tires” on them and some consensus opinions start forming, it may be difficult to distinguish what might turn into long-term successes and what might only be useful for a short while.

Even books have a limited life, insofar as the technology may advance and make portions of the book obsolete. That is why this book will be updated periodically, to try to keep it up to date with the latest changes.

GraphQL Design Principles

The preview of this section apparently resembled a Pokémon.

Key GraphQL Features

The preview of this section is sleeping in.

GraphQL Compared To…

The preview of this section was whisked away by a shark-infested tornado.