REST vs. GraphQL – A search for evidence on which is better

“ it shifts the work to someone else” I don’t think this is specific to graphQL. I’ve seen similar patterns with (to pick a recent example) shared front end component libraries. You make something more general at the expense of increasing complexity, if you have a team dedicated to that more complex proposition and enough consumers of that system you might well benefit at an org level. but if you don’t it’s easy to get caught up supporting that complexity at greater cost in time and effort than a less general solution would require. It’s a tricky call

GraphQL vs. REST somewhat resembles SQL vs. (document-oriented) NoSQL. If you can agree with your clients on certain access patterns (queries), you can design your RESTful API and your database collections, respectively, to suit these. If clients want full flexibility in what they query and avoid over-/underfetching, GraphQL and SQL (databases) might be better.

I think you misunderstand. You can write very restricted queries that mirror REST routes 1:1. No need for persisted queries.

Persisted queries enter the game when you define a query that potentially can become very complex and deep and then want to restrict the complexity in specific ways. But that is not required if you just want to mirror a RESTful API.

> What stops a frontend developer writing an ad-hoc query?

What stops them is that the "ad-hoc" query can only look like this:

    articlesWithComments($id) {
      title
      contents
      comment {
        author
        text
      }
    }

That's all. Now the only way to change this query is to remove fields but there is no way to make anything more complex. The only way to do more is to repeat the query. I.e. literally:

    article1: articlesWithComment(1) {
      title
      contents
      comment {
        author
        text
      }
    }
    article2: articlesWithComment(2) {
      title
      contents
      comment {
        author
        text
      }
    }

That will create two queries in the backend - that is the equivalent of just making two requests against the same REST route.

It _is_ possible to allow a user to change the query like this:

    articlesWithComments($id) {
      title
      contents
      comment {
        author {
          name,
          age,
          articles {
            ...
          }
        }
        text
      }
    }

But that is totally optional - you don't have to give your users this power.

I introduced graphql a few months ago to basically unblock myself from having to think about and design gazillions of custom REST endpoints for our mobile client developers. Turns out, that I don't miss doing that. REST has been a huge drain intellectually on this industry ever since people got pedantic over Roy Fielding's thesis and insisted that we stop treating HTTP like yet another RPC mechanism. The amount of debates I've been involved in over such arcane detail as the virtues of using a PUT vs POST and exactly which is more 'correct' in what situation is beyond ridiculous. I appreciate a well designed REST API as much as anyone but for most projects where the frontend code is the single customer of the API, it's not very relevant. If you are shipping SDKs to third parties, it's a different matter of course.

In any case, we now have the graphql playground where you can prototype your queries with full autocomplete (based on the schema). I've done this with third party graphql APIs; it's stupidly easy and you don't need a lot of documentation generally.

We're using the Expedia implementation for Kotlin and Spring Boot. I have a suspicion that that setup might be lot easier to deal with than Appollo and node.js since it has the important feature of using reflection for creating the schema from code. I've not written a single line of graphql schema in nearly 6 months of creating dozens of graphql endpoints. We also use kotlinx serialization to generate cross platform parsing code in our multiplatform client (we use it on Android and in the browser and soon on IOS). So, this offloads a lot of hassle of dealing with schemas and parsing both client and server side that we used to have with REST based APIs. Maybe not the most common path but worth checking out if you are looking to get started with this stuff.

My process for adding a new endpoint:

1) write a function in a spring bean that implements the Mutation or Query marker interface. Spring Boot does the rest. It generates the schema at startup time and wires everything together.

2) start a dev server, prototype the new graphql query in the playground

3) paste the working query to a new function with a multi line string along with any model classes we need in our multiplatform (js, android, and soon ios native) client library and recompile that to add the new client code for the query.

4) update the dependency on our android and web projects (we use kotlin-js for our admin UI) to use it.

5) also add the new client to our integration test project so we can write some tests for the new endpoint. We have full end to end tests of our client and API. Our server uses some mocked databases and middleware when running the tests.

It's definitely not perfect; the Expedia implementation definitely has some quirks and limitations. Also, Kotlin multiplatform has been a bit of a moving target in the last few months (though a lot more usable as of Kotlin 1.4.x). But overall it's a great setup for a small team that has better things to do than crafting custom REST APIs.

In terms of performance, technically graphql is just an HTTP POST API on top of Spring Boot (for us at least). Yes, there's a bit of overhead for query processing on the server but most of your performance is otherwise exactly the same as it would otherwise be. You of course pay a price for crafting complicated queries. But that's the same price you pay for having poorly aligned UI and REST APIs where you end up making lots of REST calls because you did not design your API right (been there, done that). Graphql just allows you to iterate on that more easily. But it's not inherently slower in any way. We are currently not doing any federation but that's mostly because we have a monolith server instead of micro-services.