In this post, I’m going to answer one simple question: How does a GraphQL server turn a query into a response?

If you’re new to GraphQL, get the three minute intro in How do I GraphQL? before reading on. That way you’ll get more out of reading this post.

Here’s the ground we’ll cover in this post:

• GraphQL queries
• Schema and resolve functions
• GraphQL execution — step by step

Ready? Let’s jump right in!

GraphQL Queries

GraphQL queries have a very simple structure and are easy to understand. Take this one:

{
  subscribers(publication: "apollo-stack"){
    name
    email
  }
}

It doesn’t take a rocket scientist to figure out that this query would return the names and e-mails of all subscribers of our publication, Building Apollo, if we built an API for it. Here’s what the response would look like:

{
  subscribers: [
    { name: "Jane Doe", email: "jane@doe.com" },
    { name: "John Doe", email: "john@doe.com" },
    ...
  ]
}

Notice how the shape of the response is almost the same as that of the query. The client-side of GraphQL is so easy, it’s practically self-explanatory!

But how about the server? Is it more complicated?

It turns out that GraphQL servers are quite simple, too. After reading this post, you’ll know exactly what’s going on inside a GraphQL server, and you’ll be ready to build your own.

Schema and Resolve Functions

Every GraphQL server has two core parts that determine how it works: a schema and resolve functions.

The schema: The schema is a model of the data that can be fetched through the GraphQL server. It defines what queries clients are allowed to make, what types of data can be fetched from the server, and what the relationships between these types are. For example:

In GraphQL schema notation, it looks like this:

type Author {
  id: Int
  name: String
  posts: [Post]
}type Post {
  id: Int
  title: String
  text: String
  author: Author
}type Query {
  getAuthor(id: Int): Author
  getPostsByTitle(titleContains: String): [Post]
}schema {
  query: Query
}

This schema is quite simple: it states that the application has three types — Author, Post and Query. The third type— Query — is just there to mark the entry point into the schema. Every query has to start with one of its fields: getAuthor or getPostsByTitle. You can think of them sort of like REST endpoints, except more powerful.

Author and Post reference each other. You can get from Author to Post through the Author’s “posts” field, and you can get from Post to Author through the Posts’ “author” field.

The schema tells the server what queries clients are allowed to make, and how different types are related, but there is one critical piece of information that it doesn’t contain: where the data for each type comes from!

That’s what resolve functions are for.

Resolve Functions

Resolve functions are like little routers. They specify how the types and fields in the schema are connected to various backends, answering the questions “How do I get the data for Authors?” and “Which backend do I need to call with what arguments to get the data for Posts?”.

GraphQL resolve functions can contain arbitrary code, which means a GraphQL server can to talk to any kind of backend, even other GraphQL servers. For example, the Author type could be stored in a SQL database, while Posts are stored in MongoDB, or even handled by a microservice.

Perhaps the greatest feature of GraphQL is that it hides all of the backend complexity from clients. No matter how many backends your app uses, all the client will see is a single GraphQL endpoint with a simple, self-documenting API for your application.

Here’s an example of two resolve functions:

getAuthor(_, args){
  return sql.raw('SELECT * FROM authors WHERE id = %s', args.id);
}posts(author){
  return request(`https://api.blog.io/by_author/${author.id}`);
}

Of course, you wouldn’t write the query or url directly in a resolve function, you’d put it in a separate module. But you get the picture.

Query execution — step by step

Alright, now that you know about schema and resolve functions, let’s look at the execution of an actual query.

Side note: The code below is for GraphQL-JS, the JavaScript reference implementation of GraphQL, but the execution model is the same in all GraphQL servers I know of.

At the end of this section, you’ll understand how a GraphQL server uses the schema and resolve functions together to execute the query and produce the desired result.

Here’s a query that works with the schema introduced earlier. It fetches an author’s name, all the posts for that author, and the name of the author of each post.

{
  getAuthor(id: 5){
    name
    posts {
      title
      author {
        name # this will be the same as the name above
      }
    }
  }
}

Side note: If you look closely, you will notice that this query fetches the name of the same author twice. I’m just doing that here to illustrate GraphQL while keeping the schema as simple as possible.

Here are the three high-level steps the server takes to respond to the query:

1. Parse
2. Validate
3. Execute

Step 1: Parsing the query

First, the server parses the string and turns it into an AST — an abstract syntax tree. If there are any syntax errors, the server will stop execution and return the syntax error to the client.

Step 2: Validation

A query can be syntactically correct, but still make no sense, just like the following English sentence is syntactically correct, but doesn’t make any sense: “The sand left through the idea”.

The validation stage makes sure that the query is valid given the schema before execution starts. It checks things like:

• is getAuthor a field of the Query type?
• does getAuthor accept an argument named id?
• Are name and posts fields on the type returned by getAuthor?
• … and many more …

As an application developer, you don’t need to worry about this part, because the GraphQL server does it automatically. Put that in contrast to most RESTful APIs, where it’s up to you — the developer — to make sure that all the parameters are valid.

Step 3: Execution

If validation is passed, the GraphQL server will execute the query.

Every GraphQL query has the shape of a tree — i.e. it is never circular. Execution begins at the root of the query. First, the executor calls the resolve function of the fields at the top level — in this case just getAuthor — with the provided parameters. It waits until all these resolve functions have returned a value, and then proceeds in a cascading fashion down the tree. If a resolve function returns a promise, the executor will wait until that promise is resolved.

That was the one-paragraph description of the execution flow. I think it’s always easier to understand things when they’re illustrated in different ways, so I made a diagram, a table and even a video that walks you through it step by step.

The execution flow in diagram form:

The execution flow in table form:

3.1: run Query.getAuthor
3.2: run Author.name and Author.posts (for Author returned in 3.1)
3.3: run Post.title and Post.author (for each Post returned in 3.2)
3.4: run Author.name (for each Author returned in 3.3)

The execution flow in text form (with all the details):

Feel free to skip this section if you already understand how it works from the diagram or the table.

Just for convenience, here’s the query again:

{
  getAuthor(id: 5){
    name
    posts {
      title
      author {
        name # this will be the same as the name above
      }
    }
  }
}

In this query, there is only one root field — getAuthor — and there is one parameter — id — with value 5. The getAuthor resolve function will run and return a promise.

getAuthor(_, { id }){
  return DB.Authors.findOne(id);
}// let's assume this returns a promise that then resolves to the
// following object from the database: 
{ id: 5, name: "John Doe" }

The promise is resolved when the database call returns. As soon as that happens, the GraphQL server will take the return value of this resolve function — an object in this case — and pass it to the resolve functions of the name and posts fields on Author, because those are the fields that were requested in the query. The name and posts resolve functions run in parallel:

name(author){
  return author.name;
}posts(author){
  return DB.Posts.getByAuthorId(author.id);
}

The name resolve function is pretty straightforward: it simply returns the name property of the author object that was just passed down from the getAuthor resolve function.

The posts resolve function makes a call to the database and returns a list of post objects:

// list returned by DB.Posts.getByAuthorId(5)
[{
  id: 1,
  title: "Hello World",
  text: "I am here",
  author_id: 5
},{
  id: 2,
  title: "Why am I still up at midnight writing this post?",
  text: "GraphQL's query language is incredibly easy to ...",
  author_id: 5
}]

Note: GraphQL-JS waits for all promises in a list to be resolved/rejected before it calls the next level of resolve functions.

Because the query asks for the title and author fields of each Post, GraphQL then runs four resolve functions in parallel: the title and author for each post.

The title resolve function is trivial again, and the author resolve function is the same as the one for getAuthor, except that it uses the author_id field on post, whereas the getAuthor function used the id argument:

author(post){
  return DB.Authors.findOne(post.author_id);
}

Finally, the GraphQL executor calls the name resolve function of Author again, this time with the author objects returned by the author resolve function of Posts. It runs twice — once for each Post.

And we’re done! All that’s left to do is pass the results up to the root of the query and return the result:

{
  data: {
    getAuthor: {
      name: "John Doe",
      posts: [
        {
          title: "Hello World",
          author: {
            name: "John Doe"
          }
        },{
          title: "Why am I still up at midnight writing this post?",
          author: {
            name: "John Doe"
          }
        }
      ]
    }
  }
}

Note: This example was slightly simplified. A real production GraphQL server would use batching and caching to reduce the number of requests to the backend and avoid making redundant ones — like fetching the same author twice. But that’s a topic for another post!

Conclusion

As you can see, once you dive into it GraphQL is pretty easy to understand! I think that’s pretty remarkable when you take into account how easy it makes things like joins, filtering, argument validation, documentation, which are all hard problems to solve in traditional RESTful APIs.

Of course, there’s a lot more to GraphQL than what I wrote here, but that’s a topic for future posts!

If this got you interested in trying GraphQL for yourself, you should check out our GraphQL server tutorial, or read about using GraphQL on the client together with React + Redux.

2018 Update: Understanding GraphQL execution with Apollo Engine

In the time since Jonas wrote this post, we’ve also built a service, called Apollo Engine, that helps developers understand and monitor what happens in their GraphQL server by providing:

• Error tracking
• Query caching
• Field-level schema analysis
• Improved tracing

If you’re interested in seeing the execution of your GraphQL queries in real life, you can sign in and instrument your server here. If you’re interested in support running a highly performant, modern application with GraphQL, we can help! Let us know.

GraphQL is just entering the mainstream as a new standard for data fetching. There are now a lot of great conversations happening around developments in the technology and new tools being built every day. One of the best parts of GraphQL is that it gives you a great common language with your team to talk about the data available in your API. But how should you talk about the query language and the core technology itself?

Well, it turns out names for almost every concept in the GraphQL language are right there in the GraphQL specification. But the spec is pretty long, so in this post I’ll lay out some of the most important concepts and terms, with concrete examples, so that you can be an expert in talking about GraphQL.

Note: If you’re trying to learn GraphQL, this isn’t the best place to start. First, read through the concepts on the graphql.org docs, then try using GraphQL with the excellent Learn Apollo tutorial, and finally come back here when you want to go deep into technical language.

Basic GraphQL queries

People commonly call everything that hits your GraphQL API server a “query”. But there are a lot of things mixed in there. What do we call a unit of work we’re asking the server to do? It could be a query, a mutation, or a subscription. The word “request” is pretty coupled to the idea of HTTP and the transport. So let’s start by defining some general concepts:

• GraphQL document: A string written in the GraphQL language that defines one or more operations and fragments.
• Operation: A single query, mutation, or subscription that can be interpreted by a GraphQL execution engine.

What are the different parts of a basic operation? Let’s look at a very simple example of a GraphQL document.

This document shows off the main building blocks of GraphQL, which specify the data you’re trying to fetch.

• Field: A unit of data you are asking for, which ends up as a field in your JSON response data. Note that they are always called “fields”, regardless of how deep in the query they appear. A field on the root of your operation works the same way as one nested deeper in the query.
• Arguments: A set of key-value pairs attached to a specific field. These are passed into the server-side execution of this field, and affect how it’s resolved. The arguments can be literal values, as in the query above, or variables, as in the examples below. Note that arguments can appear on any field, even fields nested deep in an operation.

The query above is somewhat of a shorthand form of GraphQL, which lets you define a query operation in a very concise way. But there are three optional parts to a GraphQL operation that aren’t used there. You’ll need these new parts if you want to execute something other than a query, or pass dynamic variables.

Here’s an example that includes all of them:

• Operation type: This is either query, mutation, or subscription. It describes what type of operation you’re trying to do. While all of them look similar in the language, they have slightly different modes of execution on a spec-compliant GraphQL server.
• Operation name: For debugging and server-side logging reasons, it’s useful to give your queries meaningful names. That way, when you see something wrong going on either in your network logs or your GraphQL server (for example in a tool like Apollo Optics), you can easily find that query in your codebase by name instead of trying to decipher the contents. Think of it like a function name in your favorite programming language.
• Variable definitions: When you send a query to your GraphQL server, you might have some dynamic parts that change between requests, while the actual query document stays the same. These are the variables of your query. Because GraphQL is statically typed, it can actually validate for you that you are passing in the right variables. This is where you declare the types of variables you are planning to provide.

Variables are passed separately from the query document in a transport-specific way, In today’s GraphQL server implementations, that’s usually JSON. Here’s how a variables object might look for the query above:

You can see that the key here matches the name of the variable defined in the variable definitions, and the name is one of the members of the Episode enum.

• Variables: The dictionary of values passed along with a GraphQL operation, that provides dynamic parameters to that operation.

There’s one other core concept that’s not often named, but is important when talking about GraphQL in a technical sense — what’s all that stuff between the brackets called?

The selection set is a concept you’ll see very frequently in the GraphQL specification, and it is what gives GraphQL its recursive nature, allowing you to do nested data fetching.

• Selection set: A set of fields requested in an operation, or nested within another field. A GraphQL query must contain a selection set on any field that returns an object type, and selection sets are not allowed on fields that return scalar types, such as Int or String.

Fragments

GraphQL becomes even more powerful when you introduce fragments. These bring with them a new set of concepts.

• Fragment definition: Part of a GraphQL document which defines a GraphQL fragment. This is also sometimes called a named fragment, in contrast to an inline fragment which we’ll get to below.

• Fragment name: The name of each fragment has to be unique within a GraphQL document. This is the name you use to refer to the fragment in an operation or in other fragments. Fragment names can also be useful for server-side logging, much like operation names, so we recommend using explicit and meaningful names. If you name your fragments well, you can track down which part of your code defines that fragment if you want to optimize your data fetching later.
• Type condition: GraphQL operations always start at the query, mutation, or subscription type in your schema, but fragments can be used in any selection set. So in order to validate a fragment against your schema in isolation, you need to specify which type it can be used on, and that’s where the type condition comes in.

And, just like operations, fragments have a selection set. These work just like the selection sets in operations.

Using fragments in your operations

Fragments aren’t very useful until you use them in an operation. Fragments can appear in two different ways, as we’ll see below:

• Fragment spread: When you use a fragment inside an operation or another fragment, you do so by putting ... followed by the fragment name. This is called a fragment spread, and it can appear in any selection set that matches that named fragment’s type condition.
• Inline fragment: When you just want to execute some fields depending on the type of a result, but you don’t want to split that out into a separate definition, you can use an inline fragment. This works just like a named fragment, but is written as part of your query. One difference about inline fragments is that they aren’t actually required to have a type condition, and can be used with just a directive, as we’ll see in the example below.

Directives

Directives are a way to get additional functionality out of your GraphQL server. Directives shouldn’t affect the value of the results, but do affect which results come back and perhaps how they are executed. They can appear almost anywhere in a query, but in this article we’ll focus only on the skip and include directives that are in the current GraphQL specification.

Above is a kitchen sink of examples of where you can use the skip and include directives. These directives in particular make GraphQL execution conditionally skip fields and omit them from the response. Because the syntax of directives is quite flexible, they can be used to add more features to GraphQL without making parsing or tooling more complicated.

• Directive: An annotation on a field, fragment, or operation that affects how it is executed or returned.
• Directive arguments: These work just like field arguments, but they are handled by the execution engine instead of being passed down to the field resolver.

Get involved in the conversation

A big part of the benefit of GraphQL is having a common language to talk about data fetching. Now, you’ll be well-equipped to participate in deep, technical conversations about GraphQL, for example the ongoing discussion about GraphQL subscriptions.

In this article, we’ve only covered part of the GraphQL specification — the part that deals with the query language. In a future post, we might delve into the various terms used to describe a GraphQL schema.

Want to work on GraphQL technology full-time? We’re hiring for a variety of positions including frontend, backend, and open source!

Often, GraphQL is presented as a revolutionary new way to think about APIs. Instead of working with rigid server-defined endpoints, you can send queries to get exactly the data you’re looking for in one request. And it’s true — GraphQL can be transformative when adopted in an organization, enabling frontend and backend teams to collaborate more smoothly than ever before. But in practice, both of these technologies involve sending an HTTP request and receiving some result, and GraphQL has many elements of the REST model built in.

So what’s the real deal on a technical level? What are the similarities and differences between these two API paradigms? My claim by the end of the article is going to be that GraphQL and REST are not so different after all, but that GraphQL has some small changes that make a big difference to the developer experience of building and consuming an API.

So let’s jump right in. We’ll identify some properties of an API, and then discuss how GraphQL and REST handle them.

Resources

The core idea of REST is the resource. Each resource is identified by a URL, and you retrieve that resource by sending a GET request to that URL. You will likely get a JSON response, since that’s what most APIs are using these days. So it looks something like:

GET /books/1{
  "title": "Black Hole Blues",
  "author": { 
    "firstName": "Janna",
    "lastName": "Levin"
  }
  // ... more fields here
}

Note: In the example above, some REST APIs would return “author” as a separate resource.

One thing to note in REST is that the type, or shape, of the resource and the way you fetch that resource are coupled. When you talk about the above in REST documentation, you might refer to it as the “book endpoint”.

GraphQL is quite different in this respect, because in GraphQL these two concepts are completely separate. In your schema, you might have Book and Author types:

type Book {
  id: ID
  title: String
  published: Date
  price: String
  author: Author
}type Author {
  id: ID
  firstName: String
  lastName: String
  books: [Book]
}

Notice that we have described the kinds of data available, but this description doesn’t tell you anything at all about how those objects might be fetched from a client. That’s one core difference between REST and GraphQL — the description of a particular resource is not coupled to the way you retrieve it.

To be able to actually access a particular book or author, we need to create a Query type in our schema:

type Query {
  book(id: ID!): Book
  author(id: ID!): Author
}

Now, we can send a request similar to the REST request above, but with GraphQL this time:

GET /graphql?query={ book(id: "1") { title, author { firstName } } }{
  "title": "Black Hole Blues",
  "author": {
    "firstName": "Janna",
  }
}

Nice, now we’re getting somewhere! We can immediately see a few things about GraphQL that are quite different from REST, even though both can be requested via URL, and both can return the same shape of JSON response.

First of all, we can see that the URL with a GraphQL query specifies the resource we’re asking for and also which fields we care about. Also, rather than the server author deciding for us that the related author resource needs to be included, the consumer of the API decides.

But most importantly, the identities of the resources, the concepts of Books and Authors, are not coupled to the way they are fetched. We could potentially retrieve the same Book through many different types of queries, and with different sets of fields.

Conclusion

We’ve identified some similarities and differences already:

• Similar: Both have the idea of a resource, and can specify IDs for those resources.
• Similar: Both can be fetched via an HTTP GET request with a URL.
• Similar: Both can return JSON data in the request.
• Different: In REST, the endpoint you call is the identity of that object. In GraphQL, the identity is separate from how you fetch it.
• Different: In REST, the shape and size of the resource is determined by the server. In GraphQL, the server declares what resources are available, and the client asks for what it needs at the time.

Alright, this was pretty basic if you’ve already used GraphQL and/or REST. If you haven’t used GraphQL before, you can play around with an example similar to the above on Launchpad, a tool for building and exploring GraphQL examples in your browser.

URL Routes vs GraphQL Schema

An API isn’t useful if it isn’t predictable. When you consume an API, you’re usually doing it as part of some program, and that program needs to know what it can call and what it should expect to receive as the result, so that it can operate on that result.

So one of the most important parts of an API is a description of what can be accessed. This is what you’re learning when you read API documentation, and with GraphQL introspection and REST API schema systems like Swagger, this information can be examined programmatically.

In today’s REST APIs, the API is usually described as a list of endpoints:

GET /books/:id
GET /authors/:id
GET /books/:id/comments
POST /books/:id/comments

So you could say that the “shape” of the API is linear — there’s a list of things you can access. When you are retrieving data or saving something, the first question to ask is “which endpoint should I call”?

In GraphQL, as we covered above, you don’t use URLs to identify what is available in the API. Instead, you use a GraphQL schema:

type Query {
  book(id: ID!): Book
  author(id: ID!): Author
}type Mutation {
  addComment(input: AddCommentInput): Comment
}type Book { ... }
type Author { ... }
type Comment { ... }
input AddCommentInput { ... }

There are a few interesting bits here when compared to the REST routes for a similar data set. First, instead of sending a different HTTP verb to the same URL to differentiate a read vs. a write, GraphQL uses a different initial type — Mutation vs. Query. In a GraphQL document, you can select which type of operation you’re sending with a keyword:

query { ... }
mutation { ... }

For all of the details about the query language, read my earlier post, “The Anatomy of a GraphQL Query”.

You can see that the fields on the Query type match up pretty nicely with the REST routes we had above. That’s because this special type is the entry point into our data, so this is the most equivalent concept in GraphQL to an endpoint URL.

The way you get the initial resource from a GraphQL API is quite similar to REST — you pass a name and some parameters — but the main difference is where you can go from there. In GraphQL, you can send a complex query that fetches additional data according to relationships defined in the schema, but in REST you would have to do that via multiple requests, build the related data into the initial response, or include some special parameters in the URL to modify the response.

Conclusion

In REST, the space of accessible data is described as a linear list of endpoints, and in GraphQL it’s a schema with relationships.

• Similar: The list of endpoints in a REST API is similar to the list of fields on the Query and Mutation types in a GraphQL API. They are both the entry points into the data.
• Similar: Both have a way to differentiate if an API request is meant to read data or write it.
• Different: In GraphQL, you can traverse from the entry point to related data, following relationships defined in the schema, in a single request. In REST, you have to call multiple endpoints to fetch related resources.
• Different: In GraphQL, there’s no difference between the fields on the Query type and the fields on any other type, except that only the query type is accessible at the root of a query. For example, you can have arguments in any field in a query. In REST, there’s no first-class concept of a nested URL.
• Different: In REST, you specify a write by changing the HTTP verb from GET to something else like POST. In GraphQL, you change a keyword in the query.

Because of the first point in the list of similarities above, people often start referring to fields on the Query type as GraphQL “endpoints” or “queries”. While that’s a reasonable comparison, it can lead to a misleading perception that the Query type works significantly differently from other types, which is not the case.

Route Handlers vs. Resolvers

So what happens when you actually call an API? Well, usually it executes some code on the server that received the request. That code might do a computation, load data from a database, call a different API, or really do anything. The whole idea is you don’t need to know from the outside what it’s doing. But both REST and GraphQL have pretty standard ways for implementing the inside of that API, and it’s useful to compare them to get a sense for how these technologies are different.

In this comparison I’ll use JavaScript code because that’s what I’m most familiar with, but of course you can implement both REST and GraphQL APIs in almost any programming language. I’ll also skip any boilerplate required for setting up the server, since it’s not important to the concepts.

Let’s look at a hello world example with express, a popular API library for Node:

app.get('/hello', function (req, res) {
  res.send('Hello World!')
})

Here you see we’ve created a /hello endpoint that returns the string 'Hello World!'. From this example we can see the lifecycle of an HTTP request in a REST API server:

1. The server receives the request and retrieves the HTTP verb (GET in this case) and URL path
2. The API library matches up the verb and path to a function registered by the server code
3. The function executes once, and returns a result
4. The API library serializes the result, adds an appropriate response code and headers, and sends it back to the client

GraphQL works in a very similar way, and for the same hello world example it’s virtually identical:

const resolvers = {
  Query: {
    hello: () => {
      return 'Hello world!';
    },
  },
};

As you can see, instead of providing a function for a specific URL, we’re providing a function that matches a particular field on a type, in this case the hello field on the Query type. In GraphQL, this function that implements a field is called a resolver.

To make a request we need a query:

query {
  hello
}

So here’s what happens when our server receives a GraphQL request:

1. The server receives the request, and retrieves the GraphQL query
2. The query is traversed, and for each field the appropriate resolver is called. In this case, there’s just one field, hello, and it’s on the Query type
3. The function is called, and it returns a result
4. The GraphQL library and server attaches that result to a response that matches the shape of the query

So you would get back:

{ "hello": "Hello, world!" }

But here’s one trick, we can actually call the field twice!

query {
  hello
  secondHello: hello
}

In this case, the same lifecycle happens as above, but since we’ve requested the same field twice using an alias, the hello resolver is actually called twice. This is clearly a contrived example, but the point is that multiple fields can be executed in one request, and the same field can be called multiple times at different points in the query.

This wouldn’t be complete without an example of “nested” resolvers:

{
  Query: {
    author: (root, { id }) => find(authors, { id: id }),
  },
  Author: {
    posts: (author) => filter(posts, { authorId: author.id }),
  },
}

These resolvers would be able to fulfill a query like:

query {
  author(id: 1) {
    firstName
    posts {
      title
    }
  }
}

So even though the set of resolvers is actually flat, because they are attached to various types you can build them up into nested queries. Read more about how GraphQL execution works in the post “GraphQL Explained”.

See a complete example and run different queries to test this out!

Conclusion

At the end of the day, both REST and GraphQL APIs are just fancy ways to call functions over a network. If you’re familiar with building a REST API, implementing a GraphQL API won’t feel too different. But GraphQL has a big leg up because it lets you call several related functions without multiple roundtrips.

• Similar: Endpoints in REST and fields in GraphQL both end up calling functions on the server.
• Similar: Both REST and GraphQL usually rely on frameworks and libraries to handle the nitty-gritty networking boilerplate.
• Different: In REST, each request usually calls exactly one route handler function. In GraphQL, one query can call many resolvers to construct a nested response with multiple resources.
• Different: In REST, you construct the shape of the response yourself. In GraphQL, the shape of the response is built up by the GraphQL execution library to match the shape of the query.

Essentially, you can think of GraphQL as a system for calling many nested endpoints in one request. Almost like a multiplexed REST.

What does this all mean?

There are a lot of things we didn’t have space to get into in this particular post. For example, object identification, hypermedia, or caching. Perhaps that will be a topic for a later time. But I hope you agree that when you take a look at the basics, REST and GraphQL are working with fundamentally similar concepts.

I think some of the differences are in GraphQL’s favor. In particular, I think it’s really cool that you can implement your API as a set of small resolver functions, and then have the ability to send a complex query that retrieves multiple resources at once in a predictable way. This saves the API implementer from having to create multiple endpoints with specific shapes, and enables the API consumer to avoid fetching extra data they don’t need.

On the other hand, GraphQL doesn’t have as many tools and integrations as REST yet. For example, you can’t cache GraphQL results using HTTP caching as easily as you can REST results. But the community is working hard on better tools and infrastructure. For example, you can cache GraphQL results in your frontend using Apollo Client and Relay, and more recently also on the server with Apollo Engine.

Got any more ideas about comparisons between REST and GraphQL? Please post them in the comments!