GraphQL vs REST: Overview

  1. REST and GraphQL are totally different
  2. GraphQL isn’t a magic bullet, nor is it “better”
  3. You can definitely use both at the same time
  4. GraphQL is dope if used for the right thing

A few quick differences

REST is an architectural concept for network-based software, has no official set of tools, has no specification, doesn’t care if you use HTTP, AMQP, etc., and is designed to decouple an API from the client. The focus is on making APIs last for decades, instead of optimizing for performance.

Is the API More Than Data Transfer?

One of the most common tasks REST APIs provide is CRUD via JSON, but it can do plenty more than that, such as file uploads.

POST /avatars HTTP/1.1
Host: localhost:3000
Content-Type: image/jpeg
Content-Length: 284
raw image content
POST /avatars HTTP/1.1
Host: localhost:3000
Content-Type: application/json
{
"image_url" : "https://example.org/pic.png"
}
POST /graphql HTTP/1.1
Host: localhost:3000
Content-Type: application/graphql
mutation addAvatar {
addAvatarFromUrl(image_url: "https://example.org/pic.png") {
id,
image_url
}
}

Both GraphQL and REST Prefer Evolution

One false advertised benefit of GraphQL I’ve seen suggested (in quite a few locations) is that you “never have to version anything.”

REST _is_ about evolvability, so don’t blame it for the bad habits of us RESTish people.

GraphQL makes Deprecations Awesome

One area where GraphQL excels is to make monitoring field usage incredibly easy at a technical level. GraphQL clients are forced to specify the fields they want returned in the query:

POST /graphql HTTP/1.1
Host: localhost:3000
Content-Type: application/graphql
{
turtles(id: "123") {
length,
width,
intelligence
}
}
Some

GraphQL Puts Client Performance First

GraphQL is always the smallest possible request, whilst REST generally defaults to the fullest. It’s common practice to offer options like ?fields=foo,bar or partials. Google recommend doing this for HTTP APIs, whatever that's worth.

REST Makes Caching Easier At All Levels

Caching for HTTP, common usage in REST APIs, and different types of caching are huge topics, and something that I had to split out of this article. I’ll post a followup shortly, which will be posted on the APIs You Won’t Hate Newsletter.

GraphQL is a Query Language First

A very fundamental difference here of course is that only one of these is a query language. REST APIs are often created initially simple, then slowly more and more query language-like features are tacked on over time.

{
human(id: "1000") {
name
height(unit: FOOT)
}
}

Scoped Includes Suck in Both

Using that trip example again, a client may be including passengers but realize that includes historical passengers. Don’t want to see people who left the carpool? The client has to iterate through passengers locally, removing any models where model.status != "active", which is a waste of processing on the client side.

GraphQL Devolves Power to Clients

Another question that comes up a lot for REST API developers, is:

Why Not Use Both?

The biggest oddity I notice in the “GraphQL vs REST” conversation, is the falsehood that you must pick one.

  • How different are your clients from each other?
  • Do you trust your clients to handle caching?
  • Do you want “dumb clients” that act like crawlers — knowing very little about the API, or clients that own a lot of the logic and know a lot about the API, using it simply as a data transfer?
  • Are you ok letting go of HTTP debugging proxies, cache proxies, all the knowledge your team have around HTTP, etc?
  • Are you just doing basic CRUD with simple JSON documents, or will your API need file upload/download too?

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Phil Sturgeon

Phil Sturgeon

Building API design tools @stoplightio , teaching at @apisyouwonthate, and cycling around Europe raising funding for reforestation and climate action.