Compared to SQL, this is done using an unusual manner, giving a shape of the data we want around some seed, but the approach is both expressive and efficient. In light of this query principle, it is perhaps unfortunate that GraphQL use a different syntax for the query and the response. To this regard, freebase's MQL is more pure (http://wiki.freebase.com/wiki/MQL).

About graph, I think the term applies too. Indeed, a GraphQL defines a subgraph to be extracted from a whole graph, even if the tree shape of the response forces to resort to ids to tie the loop.

Compared to a graph traversal query language like Gremlin (https://en.wikipedia.org/wiki/Gremlin_%28programming_languag...), I find the pattern approach of GraphQL simpler to grasp; and even easier to implement efficiently in a distributed setting. I implemented years ago a distributed graph database for Yahoo!; and the query language, based on shapes to be extracted around seeds, was a key design choice for an efficient architecture and short query delays.

  In an attempt to help resolve this issue, I suggest that you think of it as ProductQL or ProductAPI instead.
  
  It's not a storage layer. It's not really a query language. It's an alternative way to define an API that more closely matches the typical mental and product domains than REST.

You start with a root query object and then call a bunch of methods on it of the client's choice and put the results in a dictionary.

Then you do that recursively on the resulting objects until you have data consisting of nested dictionaries and lists containing only primitives, which is finally serialized as JSON and returned.

1) Give me data in the right shape for my problem please server.

2) Server responds with data in a shape that matches what it was asked for.

3) Update the store of your frontend and trigger any updates to UI (react does this automatically).

Save countless hours of writing fine grained rest APIs to support various different ways of requesting data or munging data into the right format on the client.

And by the way we've made it super easy to bundle requests together in a nice way saving trips to the server.

But at the end of the day, most data can be considered graph data. It doesn't have to be represented as a formal graph.

Whereas contrasting with REST versioning or traditional versioning, it becomes quite difficult to mix API versions internally (each callsite needs to specify their desired api version before specifying fields) or impossible outright. If the latter, you're then forced to migrate all at once from a given version to another, which requires a ton of coordination across teams and big scary "flip the switch" moments.

This gets worse as you scale up your org, which is why GraphQL has served FB well.

It's totally unclear to me that GraphQL solves data migration problems.

Ultimately syntax is useful to express domain-specific concepts in a terse way.

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
      }
    }
  }

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.

https://github.com/facebook/relay/blob/master/src/network-la...

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.

http://www.odata.org/getting-started/understand-odata-in-6-s...

https://github.com/OData/WebApi

http://facebook.github.io/graphql/

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.

The proliferation of ad-hoc REST endpoints is a serious problem. Standards like JSON API (http://jsonapi.org/) do a good job of mitigating the issue (and are probably a good first step for preparing your API for being encapsulated within a GraphQL server), but they are just a band-aid around the problem.

We've all concluded that mobile apps (for now) should only be making one API request to get all data needed (if possible), so we end up constructing custom end-points per use-case that return exactly what's needed. Then a new version of the app comes along with slightly different data requirements, so we make a new end-point. We end up in a really bad place. Developer discipline is part of the problem, but the fact is that we're probably using the wrong technology.

SOAP was awful, REST is much nicer. But GraphQL is a dream. It genuinely feels like every time I add a new piece of data to my schema, my productivity accelerates. A well-considered, well-maintained GraphQL server is a significant improvement over REST endpoint. GraphQL may not be the ultimate solution here, but it solves a lot of pain-points i've been having for the last few years.

For example, a query like "user {moviesWatchedByUser {usersWhoWatchedMovie {moviesWatchedByUser {usersWhoWatchedMovie ..." is allowed by GraphQL and will generate output with size exponential in the input size.

You can also do "{a1: expensiveOperation, a2: expensiveOperation, a3: expensiveOperation, ..." and trigger expensiveOperation an arbitrary number of times (for each item in the list you apply that to).

By using a sequence of fragments that include the next fragment more than once, it looks like you can trigger expensiveOperation an exponential number of times.

It's not clear if there is a way to prevent all this without severely impacting usabilty (by warping the schema design and adding GraphQL limits to handle this) or reliability (by enforcing hardcoded low resource usage limits).