GraphQL is Not “Better” Than REST

GraphQL is Not "Better" Than REST

As if that makes any sense

I worked in a company that successfully deployed and capitalized on the exponential value from a Hypermedia system in production. After we proved the practical business value of that Hypermedia system, this question still kept popping up:

Is GraphQL better than REST?

HTTP means Hypertext Transfer Protocol. Hypermedia is a mandatory constraint for you to apply the REST Architectural style. Roy Fielding, the creator of REST and earlier designer of the Web, has put it very clearly:

[…] if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API […]

— Roy Fielding on REST APIs must be hypertext-driven

Interest in GraphQL is growing nowadays. It's the shiny new thing. However, there are many popular talks and blog posts out there with incorrect information about Hypermedia and how it relates to REST. Likewise, there are some not so popular talks and blog posts with valuable content in this area that can explain their relationship.

To answer the question of GraphQL vs. REST, I decided to produce a workshop. The purpose of the workshop was to present an online talk every day at lunchtime. In this post, I'll share with you all the talks along with a summary, plus a blog post and the original dissertation. I encourage you to watch all of them, in the same order, from the beginning to the end. If you don't, then the conclusion won't make any sense — as much as the conclusion itself.

1. Talk: GOTO 2014 • REST: I Don't Think it Means What You Think it Does • Stefan Tilkov

Stefan Tilkov clarifies the most common misconceptions about REST: It's not about pretty URLs; it's not about HTTP verbs; it's not about links. The talk serves as an introduction to the topic. It will make you raise the eyebrows.

You may end up with a few questions such as "how does a code using this look like?". Likewise, you may end up with a few defensive thoughts such as "the industry has evolved this old idea already!".

You'll get the answer to those questions and concerns in the following talks. This one is only about clarifying the most common misconceptions.

2. Talk: Hypermedia APIs — Jon Moore

In this talk, Jon Moore shows a practical example of how the server can upgrade without changing any code in the client. He also shows some examples of how to optimize a client that makes too many HTTP requests into only one. It's the perfect runnable example of how to apply the Hypermedia constraint of REST.

After watching this talk, you may end up with a few questions such as "What's the business cost of this?". Likewise, you may end up with defensive thoughts such as "This is XML, old and outdated, why would I care?".

The majority of the cost is on learning, which applies to everything related to programming and gets better with practice. The implementation cost of REST is the same as any other API you are used to developing.

The speaker uses XML, but you may as well achieve the same outcome with JSON. The syntax for the language you use is irrelevant to understand the concept in this talk.

Keep that in mind.

3. Talk: "A no-nonsense GraphQL and REST comparison" by Phil Sturgeon

Everybody talks about REST vs. GraphQL. However, Roy Fielding has defined the REST Architecture Style in his dissertation using a very objective set of constraints.

According to Phil Sturgeon, the GraphQL comparison makes no sense if you look at the real value and tradeoffs behind REST.

4. Talk: YOW! 2017 Mike Amundsen — Twelve Patterns for Evolvable Web APIs

In this talk, Mike Amundsen uses the REST Architectural Style to explain 12 patterns to develop APIs. He uses features that are already built-in on HTTP. Those patterns had contributed to the long-lived existence of the Web since its inception almost 30 years ago.

5. Post: GraphQL vs. REST: Overview

GraphQL is incorrectly considered by some to be a "replacement" to REST. GraphQL is a newer concept, being released by Facebook publicly in 2015, whereas REST was a dissertation published by Roy Fielding in 2000, popularized by companies like Twitter (quite inaccurately) in 2006.

This article aims to cover a few notable differences.

This post is a complementation of number "3".

6. Dissertation: Architectural Styles and the Design of Network-based Software Architectures

This is the link for the original dissertation, unchanged since 2001.

In this document, Roy Fielding introduces the idea of "Architectural Styles" for network-based architectures. He defines the term objectively and then uses Representational State Transfer (REST) as the primary example of an Architectural Style in Chapter 5. I recommend reading the whole dissertation, not just Chapter 5.

The document is a guideline to teach how the Web should evolve and maintain the attributes which kept it stable for more than 30 years. In the context of REST, the HTML specification is the API, and the browsers are the clients. If you change HTML code in the application server, you don't have to create versions or change the code inside the browsers.

7. Post: Richardson Maturity Model

Here's a summary of the post:

A model (developed by Leonard Richardson) that breaks down the principal elements of a REST approach into three steps. These introduce resources, HTTP verbs, and hypermedia controls.

In this post, Martin Fowler shows that there are different levels of maturity for building APIs using HTTP that abides by Roy Fielding REST Architectural Style. He presents an eponymous model from Leonard Richardson.

The model starts on Level 0 when there's a lack of understanding of the idea. That causes constant API breakage and the massive cost of development (The Swamp of POX). Later, you learn better and achieve more fundamental understanding, which brings less breakage, and low cost of development (Hypermedia Controls).

If you see yourself in one of the first levels, it's a hint that there's more to learn. It's a good idea to try and understand the benefits from higher levels before moving further into designing a critical API.

Click here to see the original talk from Leonard Richardson. It contains essential information and context behind his model.

Click here for a 2019 post from Phil Sturgeon regarding the Richardson Maturity Model. In that post, Phil goes more in-depth into each of the levels and gives further perspective about GraphQL at the end.

So, after all, what's the difference between GraphQL and REST?

GraphQL is a Query Language; REST is not. GraphQL is one media type among many, such as:

• text/html
• text/calendar
• application/collection+json
• application/vnd.api+json
• application/vnd.siren+json
• …and more

REST is an Architectural Style, as Roy Fielding defined in his dissertation, GraphQL is not. REST represents a series of tradeoffs that documents the success of the Web. If you use Hypermedia as Roy defined in his dissertation, you'll achieve a similar level of robustness, evolvability, and longevity as the Web and text/html. Otherwise, you won't.

Neither GraphQL nor REST is supposed to be "better" than the other one. It doesn't make sense to compare them in the context of "how to build an API." However, many people still do, and that doesn't make it more right. It only shows a lack of understanding of the fundamentals and tradeoffs surrounding the paradigms of how network-based software systems communicate.

If you haven't watched the talks and read the blog posts, this conclusion won't make any sense for you. You might as well stop reading. However, if you have watched the talks and read the blog posts, it should be more apparent by now that GraphQL and REST are mutually exclusive.

It makes no sense to compare REST and GraphQL, but for some reason, we do.

It's time to stop.

If you talk about any of these concepts, put them in their place. For REST, talk about the conceptual tradeoffs of the Architectural Style, and the differences when building a new media type for the Web. For GraphQL, talk about the circumstances where GraphQL media type may or may not provide significant value to a developer for querying data in another system.

If you want to compare something, compare two media types such as text/html with application/graphql, not REST with application/graphql. It's like comparing Functional Programming with C#.

Stop bikeshedding on pointless comparisons, which makes you sound stupid.

It's like comparing cars and oranges.

That doesn't make any sense.

Thanks for reading. If you have some feedback, reach out to me on Twitter, Facebook, or Github.

Thanks to Phil Sturgeon, Mike Amundsen, Danil Suits , Robin Venneman , Chris Holland and Markus Tacker for their insightful inputs to this post.

Wanna chat in person? You can find me in the Sydney Software Crafters meetup.