Skip to content

GraphQL as a Question to the System

Half a year after the specification, this post sorts out what is really new about GraphQL – and which questions nobody had answered yet in early 2016.

≈ 12 min readSoftwareGraphQLAPI

GraphQL as a Question to the System

“A query language for APIs” – that is how Facebook describes GraphQL in the specification, which has been public as a working draft since July 2015. The term quickly leads you astray. If you hear “query language,” you think of SQL and assume a query language for databases, somehow extended to the web: the client sends a SELECT, the server passes it through. That is not it, and the misunderstanding is dangerous, because it makes GraphQL seem either too powerful (arbitrary queries against my data) or too trivial (yet another ORM over the network).

GraphQL does not query tables, knows nothing about joins and has no opinion about where data lives. What gets queried is something else: a type system that the server publishes. The client phrases its question in the terms of this type system, the server answers exactly that question – and where the data comes from, whether from a database, from three internal services or from a file on disk, remains entirely the server’s business. Half a year after the release, it is worth taking a sorting look: what of this is really new, and what is just new syntax for old ideas?

Who is actually asking the question here?#

The core fits in one sentence: REST answers questions the server asked itself – GraphQL lets the client ask the question.

That sounds more polemical than it is meant. A well-thought-out REST design is a collection of answers: GET /posts/42 returns what the developer of the endpoint considered relevant for an article. When the endpoint was designed, someone guessed which fields a client would probably need – and, when in doubt, packed in a few more. This answer is frozen. If a view comes along later that only needs the title and author names of the last ten articles, it has two options: call the fat endpoint and throw most of it away, or request a new, tailor-made endpoint. Both happen constantly in real projects, and both create costs – once in the network, once in coordination between teams.

GraphQL reverses the direction. The server no longer says “these are my answers,” but “these are the terms in which you may ask.” The concrete question – which fields, how deeply nested, in which combination – is phrased by the client itself, per view, per release, without checking back with the server team. That is the real shift, and it is at least as interesting organizationally as technically.

The schema as contract and domain language#

For the client to ask, the server has to disclose its vocabulary. That happens in the schema, and for me this is where the underestimated quality of GraphQL lies: the schema is not just a contract about data shapes, it is a domain language. Types name things in the domain, not rows in a table. In the compact schema notation that has become common in examples and talks, it looks roughly like this:

type Author {
  id: ID!
  name: String!
  posts: [Post]
}

type Post {
  id: ID!
  title: String!
  body: String!
  author: Author!
  comments: [Comment]
}

type Comment {
  id: ID!
  text: String!
  author: Author!
}

type Query {
  post(id: ID!): Post
  latestPosts(count: Int): [Post]
}

You can show this schema to an editor and discuss whether a comment really always has an author. The exclamation point is not a formality but a domain statement: author: Author! claims that there are no orphaned comments. Whether that is true is known not by the client developer, but by whoever knows the legacy data. I have rarely had such discussions about database schemas – around the GraphQL schema they arise almost by themselves, because it sits exactly on the boundary between the teams and both sides can read it.

The Query type stands out: it does not describe a thing but the entry points – the questions the system allows at all. That, too, is a design decision of the server. GraphQL does not open up all data indiscriminately; it opens exactly the roots that are in the schema, and from there the edges that the types define.

The query: the shape of the answer is the shape of the question#

The second property that stands out immediately in daily work: a GraphQL query is declarative, and the answer has exactly the shape of the question.

{
  post(id: "42") {
    title
    author {
      name
    }
    comments {
      text
      author {
        name
      }
    }
  }
}

The answer to it:

{
  "data": {
    "post": {
      "title": "GraphQL as a question",
      "author": { "name": "Ada" },
      "comments": [
        { "text": "Nice read!", "author": { "name": "Grace" } }
      ]
    }
  }
}

Not one field too many, not one too few, and the nesting of the answer mirrors the nesting of the question. At first this looks like a convenience, but it has practical depth: the client code that processes the answer sits right next to the query that describes it. If you change the view, you change the query, and the data shape follows. Facebook’s Relay, available as open source since August 2015, takes exactly this idea to the extreme and lets every component declare its own data requirements. You do not have to use Relay to benefit from the idea – the query alone already forces a clarity that never emerges with “we just take whatever the endpoint returns.”

Resolvers: where the truth lives#

That leaves the question of how a declarative question turns into a concrete answer. The reference implementation graphql-js answers it with a simple principle: every field has a resolver function. It receives the parent object and the arguments and returns the value of the field – synchronously or as a promise.

import {
  GraphQLObjectType,
  GraphQLID,
  GraphQLString,
  GraphQLList,
  GraphQLNonNull
} from 'graphql';

const postType = new GraphQLObjectType({
  name: 'Post',
  fields: () => ({
    id: { type: new GraphQLNonNull(GraphQLID) },
    title: { type: new GraphQLNonNull(GraphQLString) },
    author: {
      type: authorType,
      resolve: (post) => db.findAuthorById(post.authorId)
    },
    comments: {
      type: new GraphQLList(commentType),
      resolve: (post) => db.findCommentsByPostId(post.id)
    }
  })
});

const queryType = new GraphQLObjectType({
  name: 'Query',
  fields: {
    post: {
      type: postType,
      args: { id: { type: new GraphQLNonNull(GraphQLID) } },
      resolve: (root, args) => db.findPostById(args.id)
    }
  }
});

In graphql-js, you currently build the schema programmatically from such type objects; the compact schema notation from above mainly serves communication. More important than the API details is the place where truth emerges here: in the resolver. Whether author comes from the same database as the post, from another service or from a cache – that is decided by this one function, and only by it. The schema promises the shape, the resolver delivers the content. This separation makes GraphQL a facade: you can clean up behind it, merge services or split them apart without any client noticing, as long as the schema holds.

In a project at the end of last year, I put a small prototype with graphql-js in front of two existing internal services – nothing in production, an experiment over the holidays. The surprising experience was not the query language, but how quickly the discussion in the team shifted from endpoints to terms. Instead of “which endpoint returns this field,” the question suddenly became “does this field belong on this type.” That is a better question.

Overfetching and underfetching: the problem actually solved#

If you ask soberly which concrete problem GraphQL solves, I keep ending up with two that share the same root. Overfetching: the endpoint returns more than the view needs, and mobile clients pay for it with data volume and battery life. Underfetching: the endpoint returns less than the view needs, and the client works its way through further endpoints one after another – each round a full network latency, on mobile networks often three-digit milliseconds.

flowchart LR
  subgraph REST["REST – three rounds for one view"]
    C1[Client] --> E1["GET /posts/42"]
    C1 --> E2["GET /posts/42/comments"]
    C1 --> E3["GET /authors/7"]
  end
  subgraph GQL["GraphQL – one question"]
    C2[Client] --> Q["POST /graphql<br/>one query, one round trip"]
    Q --> R["Resolver"]
    R --> S1[("Database")]
    R --> S2["internal service"]
  end

Both problems disappear because the question lies entirely with the client: it asks for everything it needs and nothing beyond that, in a single round trip. The rounds between the data sources still take place – but on the server side, in the data center, where latency is cheap. That is exactly why Facebook built GraphQL for its mobile applications, and exactly why the benefit is greatest where clients talk over poor networks. If you build an internal API between two servers in the same rack, GraphQL solves a problem you may not have at all.

GraphiQL: the window into the system#

One aspect is often left out in discussions about the language and the type system: GraphQL servers are introspectable. The schema can be queried at runtime – with a GraphQL query about the schema itself. GraphiQL builds on this: the browser-based explorer that Facebook published together with the reference implementation. You point it at an endpoint and get:

  • autocompletion for fields and arguments, straight from the schema
  • inline documentation for every type and every field
  • validation of the query as you type, before the first request
  • a window for trying things out, without a line of client code

That changes how you get to know an unfamiliar API. Instead of reading documentation wikis that nobody has maintained for three versions, you explore the system itself – and the information cannot go stale, because it comes from the running server. While playing around, I noticed that GraphiQL disciplines schema quality along the way: when every field name is immediately visible and autocompleted, bad naming visibly hurts.

What is open in early 2016#

So much for the praise. To be honest, a stock-taking also has to include what the specification and the young community have not answered yet. Four points occupy me at the moment:

  • Caching without URLs
  • the N+1 problem in resolvers
  • permissions per field
  • versioning – the promise of the “versionless API”

With caching, GraphQL initially loses something that REST gets for free. HTTP caching lives on the URL as the cache key: browser, proxy and CDN can cache GET /posts/42 without understanding the content. A GraphQL request is a POST against a single endpoint – to the HTTP infrastructure, all requests look the same. Relay answers this on the client side with a normalized cache over object IDs, which is elegant but only helps in the client. For the intermediate layers, there is no convincing answer as of today.

The N+1 problem arises directly from the resolver model. The query latestPosts(count: 10) with the field author calls the author resolver ten times – in the naive case ten individual database queries for a list that a single query could deliver:

flowchart TD
  Q["latestPosts(count: 10)<br/>with field author"] --> P["Resolver latestPosts<br/>1 query"]
  P --> A1["Resolver author<br/>Post 1"]
  P --> A2["Resolver author<br/>Post 2"]
  P --> An["Resolver author<br/>Post 10"]
  A1 --> DB[("10 individual queries<br/>instead of one")]
  A2 --> DB
  An --> DB

For this, Facebook released DataLoader in the fall, a small, fresh project that collects load operations per request, deduplicates them and executes them in batches. The approach looks viable, but it is not an established pattern yet – you have to know it and build it in deliberately, otherwise the most elegant schema produces a miserable database load.

Permissions are the question I respect the most. With REST, you authorize per endpoint, and the model is well understood. In a graph, potentially every type is reachable from every other type via edges: if Comment has a field author and Author has a field posts, you get from the most harmless comment to the complete list of works. The consequence is uncomfortable: authorization has to be thought of per field, sensibly in the resolvers – and a widespread, proven pattern for it simply does not exist yet.

That leaves versioning. Facebook advertises GraphQL as a “versionless API”: instead of building /v2/, you extend the schema, mark old fields as deprecated – the specification explicitly provides for deprecation – and watch which clients still query them. Because every query names its fields explicitly, the server knows for the first time exactly what is actually used. On paper this convinces me; whether it sustains the discipline over years, nobody can prove in early 2016. I note it as a promise, not as a property.

The bottom line#

What is really new about GraphQL is not in the syntax and not in the word “graph.” What is new is the distribution of responsibility: the server defines the domain language and is responsible for the truth in the resolvers, the client phrases its question itself – completely, type-checked, answerable in one round trip. Overfetching and underfetching, the two chronic points of friction between API teams and client teams, disappear almost as a side effect.

The open questions are real: caching, N+1, field permissions, the unproven versioning promise. None of them looks unsolvable, but if you use GraphQL in production today, you answer them yourself and carry the risk for it. For me that means: keep working with prototypes, take the schema seriously as a basis for conversations with domain experts, and keep the server side small. I consider the idea that a client asks the system a question instead of fetching prefabricated answers to be right regardless of the tool – and if GraphQL does not catch on, the next technology will have to pick up exactly this idea again.

Further reading#

Revised and translated from German with the help of AI.