#restfulprogramming

Y’all, I’m so bummed, I wrote SO MUCH about GraphQL and then my computer froze and it got deleted. I’m gonna try to reproduce it though. If you don’t think this post is excellent, just remember it was probably way better the first time I wrote it.

So, to understand the big fuss about GraphQL, it helps to first understand the existing infrastructure it attempts to replace: REST.

What is REST?

REST stands for REpresentational State Transfer and is the architectural system that underlies the world wide web. In a RESTful system, everything -- a user, a post, a comment -- is a resource, and resources can be accessed via the HTTP methods GET, POST, PATCH, and DELETE.

Okay, sure, everything is a resource -- what else would it be? What does that even mean?

I know. Strangely, defining REST seems to be a pretty controversial topic and the deeper I dig, the more complicated and frayed the different explanations become. It’s a concept that is so fundamental to the proverbial Way Things Work that it can be hard to imagine an alternative (well, okay, maybe you know about SOAP, but I’m not going to get into that here). As a someone who wasn’t familiar with the context around REST, I had a bit of a “What the hell is water?” moment when first researching it. Here are a couple of resources that I found enlightening:

How I Explained REST to My Wife.

This StackOverflow answer

If you’re confused, don’t worry. For the purposes of understanding GraphQL, all we really need to know about REST is that it allows you to request a resource at a particular API endpoint like /users/:user_id, and it returns the corresponding data, usually as JSON, or maybe XML if you’re old school. We might get back:

{

    id: 23980138,

    name: “Pam Beesly”,

    username: “pamster227”,

    age: 32,

    job: “receptionist”,

     post_ids: [32520249, 73457894, 3897984, 2398552, 98200235]

}

This is great if we wanted all this data about Pam. But what if our end goal were just to display the title of her most recent post? We would first need to request her user data to get her post ids, and then we would make a separate request to retrieve the title. Moreover, a typical /posts/:post_id endpoint would probably return a lot of other data about each post that we didn’t need:

{

     post_id: 98200235,

     author_id: 23980138,

     date_created: “12-08-2011-13:11:37”,

     date_modified: “12-08-2011-13:11:37”,

     title: “Why I’m thinking about quitting my job”,

     body: “Michael is just too much for me to deal with. So is Dwight. Angela yelled at me today. I can’t take this anymore!”,

     comments_allowed: false,

     is_private: true

}

We only wanted the title! We had to make two costly round trips to the server (one for the post IDs, the other for the post title) and we ended up getting a lot of extra baggage. 

Maybe if this request is really common, we’ve written some custom backend logic that takes a user ID and directly returns the titles of that user’s most recent post. This is nice because it saves us from making two trips to the server, and it ensures we’re only using your iPhone’s measly 2GB plan for data you will really use. But to do this, we probably have to hit a custom endpoint like /mostRecentPostTitle/:user_id. This endpoint only serves one function, and if the data needs on the frontend ever change -- perhaps in another context we want preview text of the post’s body -- we have to go back and change that logic on the server as well as the client.

The backend is brittle! The data needs on the frontend change more rapidly than they used to. People don’t want to wait for the page to load while you make another round-trip service call. And with the proliferation of mobile, minimizing data usage is more important than ever.