dschafer

We've been using GraphQL at Facebook in production for almost five years now, and it powers a huge amount of our iOS/Android app's API traffic. We also did a comprehensive revisit of the core concepts when we open sourced it in 2015, and we heavily use tools like GraphiQL internally. I can definitely assure you that Facebook's support/usage of GraphQL isn't a fad.

Yeah, introducing a new field and deprecating the old one seems like the best option here. The nice thing is that while this introduces new functionality, there's still only one version of the server; if you query for `homePlanet`, you always get the name, if you query for `homePlanetDetails`, you always get the planet object. This is particularly useful for tooling, since the API response is a function only of the access token and the query.

FB's GraphQL APIs are only used by our first-party applications; for third-party APIs (where you don't control the callers), it definitely gets trickier for the reasons you note. One option would be to do some analysis of the query in advance (effectively, assign each field a "cost"), and reject queries that have too high of a cost. The "cost" metric could basically be "around how many objects will this return", so in the

  user {friends {friends {friends {friends{id}} } } }

case (which is the canonical example in FB's schema of a crazy query), we would note that there's a 5000 friend limit, and so that query would potentially query 5000^4 = 6.25e14 nodes, and based on that we would (hopefully) reject it.

When building out a GraphQL schema, the schema developer chooses which functionality to expose to the client. So rather than having the client do operations or predicates directly, the server declares what functionality is available, and might expose functionality that ordinarily would have used operators or predicates.

For example, we might have the following query on Facebook's GraphQL schema:

  {
    user(id: 4) {
      followers(isViewerFriend: true, birthdaysInRange: {before: -2, after: 2} orderBy:NAME) {
        name
      }
    }
  }

EDIT: fix code formatting

Which fetches Zuck's followers, and filters it to only my friends, and only those friends whose birthdays are within two days of today, and then orders them by name.

The `isViewerFriend`, `birthdaysInRange` and `orderBy` parameters were explicitly added to the API by the API developer for clients to use.

So clients don't have the ability to do arbitrary operators, but we also know that the client is only using functionality in the API that the API developer chose explicitly to allow.

The GraphQL API acts as a layer atop application code; it assumes that the application code takes care of any access controls (since those access controls would apply to anyone querying that data, not just GraphQL). So there's nothing for access control built-in to GraphQL, but GraphQL can map to arbitrary access controls that exist in the application layer.

The GraphQL server can pass down authentication information through the query using `rootValue` (for example, it might pass the OAuth access token that the client provided in the request), which the mapping from GraphQL-to-application-code can pass to the application code's access controls.

GraphQL queries are hierarchical so that the response mirrors the structure of the query. We found that there were needs of the query (query parameters and directives, for example) that didn't feel ideally represented in JSON, which is why we have a different syntax.

We've got a reference lexer and parser in JS at https://github.com/graphql/graphql-js/tree/master/src/langua..., and we have a parser in C++ with C and C++ APIs (that can be used to build a parser for other languages) at https://github.com/graphql/libgraphqlparser.

Yep, GraphQL is agnostic as to how your data is stored. For example, https://github.com/graphql/swapi-graphql/ is a GraphQL schema that is backed by the swapi.co API. The examples at https://github.com/graphql/graphql-js/blob/master/src/__test... are backed by in-memory JSON objects. At Facebook, we have GraphQL types backed by data stored in a number of backends, including types backed by SQL tables.

It's passed to that function in the reference implementation, but a server would probably create a helper function that runs a query for a particular schema. For example, you can just pass a query to Facebook's GraphQL endpoint (without specifying a schema), and it will run the query on the Facebook schema.

GraphQL doesn't prescribe a particular approach to mutations; it allows the server developer to specify what mutations are available. For example, at Facebook we have a storyCreate mutation, and a friendRequestAdd mutation.

Mutations are just top level fields, but with side effects; because they are fields, the client sends up a selection set with the mutation. This allows the client to receive whatever data it needs to refresh, as the response to the mutation.

GraphQL was originally designed for reads, but we added write support to solve the parallel problem we were having with writes: different clients wanted different data back from the server after they performed a write. GraphQL gave us that capability.