Great point about not focusing on code reduction. GraphQL is such a big change from rest that the primary benefit will be different for each team you ask. Form my perspective in a startup with ~50 developers is this:

By providing a clear and powerfull interface you can significantly reduce inter-team communication leading to both higher throughput and faster iteration cycles.

From a technical perspective reducing round trips is important, especially on mobile devices and GraphQL makes this trivially easy.

These two points I suspect is the primary reason many medium+ sized development teams end up implementing their own bastardised version of GraphQL in their existing rest api. Many people we talk to at http://graph.cool are interested in deploying a thin GraphQL wrapper on top of their existing api for exactly this reason.

GraphQL works really well for some edge cases, and those edge cases will be more evident if you're FaceBook. For smaller projects, the benefits of integrating GraphQL libraries on the client and the server v/s special handling for a limited set of APIs is not obvious.

By special handling, I meant:

    https://example.com/friends?fields=name,pic,posts&posts_len=10

The vast majority of APIs will not require this kind of result-shaping. And for those that do, passing comma separated fields (using a protocol teams already understand) is worth trying before adopting something more drastic. Of course, YMMV.

Often what gets lost in these kinds of discussions is the difference between what is theoretical and what is practical. Yes, you can have a perfectly designed REST API which has all of these features.

What happens, though, when you want a new piece of data? Do you redesign the API to fit this new piece of information into it or do you make a new endpoint? What if the new piece of data doesnt actually belong with `friends` but if you do the fetch for friends and this new piece of data at the same time you can get a performance boost? Do you make a new endpoint `friendsandfamily`?

Now, what if you want to migrate all calls over to that endpoint, you now need to figure out if any of your frontend code or legacy systems are still using that old endpoint before you remove it.

The maintenance of that system is much higher because you've conflated what data you want with how you want to get it.

how is this solved by GraphQL though?

You still need to add a new edge `friendsandfamily` (same as adding to a new endpoint) or add a new a field to the existing object (same as adding a new field to the existing endpoint).

What am I missing?

(1) GraphQL returns only what the client asks for. No need to worry that adding to an existing resource will increase response times or bloat the response for existing queries.

(2) If you decide to go the friendsandfamily route, you'll just be adding `family`. You won't have `friends` endpoint and `family` endpoint and `friendsandfamily` endpoint. A GraphQL schema doesn't increase combinatorially in size; rather the possible compositions increase combinatorially.

for 2) isn't this the same as adding an optional "include=family" to the existing friends endpoint?

This is what the JSONAPI spec suggest too.

Yep. You can use query parameters to fix 1) and 2).

Go down the rabbit hole a little bit further, and you have GraphQL (if you're lucky....if not, you'll just have a mess).

I gave a talk about this recently [1]. One of the subtle points of why GraphQL has the potential to be more productive for smaller teams & projects is because it is well specified. Standards are a bit constraining, but they're also enabling. There are already some nice tools built on top of GraphQL and more will come as the project matures. This is of course the same value proposition as Swagger, JSON-API, and other formalizations of REST. In my opinion those projects are likely more mature today - especially for native mobile apps. But in a few years? I suspect GraphQL will be more productive even for small teams.

[1] https://www.youtube.com/watch?v=P0uJHI7GjIc

Even when it does require result shaping you can just use a non-standard-REST POST request where the requested information is in the HTTP body. Implementing GraphQL on the server side seems like a lot of effort for no immediate gains. I am pretty sure it works very well for Netflix and Facebook though.

Does GraphQL actually provide performance advantages right now? From what I've read about it, it seems like it suffers from a bit of an N+1 queries problem if you don't do a lot of custom optimization, which seemed like considerably more work than a REST API.

Just like SQL, GraphQL needs a good query planner for complicated queries.

REST is more like a NoSQL database where you write all the joins by hand: on the plus side, you get to control the query execution, on the negative side, you have to control the query execution (also you have round-trips and lack some possible internal optimizations).

The "performance" of GraphQL refers to the fact that most things can be queried in one round-trip, rather than many for RPC, REST, or vanilla HTTP. Each of these are abstractions, not implementations.

So the maximum performance of GraphQL is better than the maximum performance of REST, particularly over mobile networks...as you said though, the devil is in the implementation.

fwiw I think Facebook's current implementation interfaces with a read-through cache. I think they've managed to make it fast without having to spend all of the effort on query planning that way.