Careful about the GraphQL Burger 🍔
With Great Customization comes Great Responsibility 🕸
A while ago a tweet containing this image got pretty viral in the REST & GraphQL communities. It also got pretty intense, with people arguing back in forth if this image is a good thing or not for GraphQL. An analogy can only go so far, and at some point it falls apart when trying to have a productive conversation.
What is this image trying to say? From my perspective, probably that GraphQL is a highly customizable API that lets clients select the use cases and data shapes they need. It is an undeniably strong point of GraphQL, especially when a one size fits all API starts struggling and the number of client use case variations is getting high.
One thing that people more familiar with REST APIs notice right away though, is that this comes with some costs! While GraphQL allows us to construct the burger exactly like we want, that’s not always what clients desired. When I go to a restaurant with a gigantic menu that can be customized as I want, it’s hard to make a choice, and I have more chances of creating something that was not intended to be great. In fact, if we push the analogy a bit further, a GraphQL “Menu” is not the easiest to reason about. When somebody reads documentation or looks at a GraphQL schema we see something like this — a giant graph of use cases, with a bunch of root fields from where we can start our experience. Which subset of this graph we need to select to solve our use case is the hard part. Compare that with a more endpoint based API where usually a simple endpoint will be there for a use case.
From an API provider perspective, it also has some costs. Consistency is not only about our codebase. It is also how consistent the experience is across clients. GraphQL allows clients to create their own experience, for better, and for worst. It’s not black or white though, we can actually design our GraphQL API knowing that this is a danger.
From a public API perspective, this is even clearer. While GraphQL brings a lot of power to individual clients, as an API provider, we still want to keep ease of use, a good onboarding experience and consistency for clients.
But again, this is not a only a GraphQL thing! Check out this endpoint based API, where just like the image above, we can build the burger we want:
https://api.restaurant.com/burger?ingredients=bun,saucehttps://api.restaurant.com/burger?ingredients=lettuce,bun,patty
And these discussions were had way before GraphQL even existed. This is again just about customization versus optimization. Whether you need api/bunlessBurger or api/burger?without=bun is up to you and the trade-offs you’re making. It’s hard to generalize the best solution here.
So where am I going with this? Well first I think these debates don’t have much value unless we clearly state our requirements and the trade-offs we’re willing to make. Second, a lot of the debates I see have nothing to do with REST vs GraphQL, but more “this API design” vs “that other API design”. There’s a lot of ways we can design just within what’s called REST or GraphQL.
Finally, I still think that especially as a public GraphQL, we must be careful of the power we give clients by balancing it with a few things:
- Staying away from designing a GraphQL API with too much focus on data by focusing on clear use cases.
- Documenting our GraphQL API with use cases in mind and how to achieve what clients are looking for. Generating documentation from a GraphQL schema is cool but it will not be enough. Same thing could be said from a typical REST API but GraphQL makes it even more obvious. Unfortunately for us that part is harder to automate and I think it needs a human touch!
- Be aware of this power, and the responsibility it comes with! đź•·
