Leave the REST to GraphQL

REST. Representational state transfer. The gold standard. You see it on software job descriptions everywhere. Every backend and full-stack engineer needs to know it. At least, that’s what we thought. Then came a new kind of API spec, GraphQL.

GraphQL is a query language designed to build client applications by providing an intuitive and flexible syntax and system for describing their data requirements and interactions.

— GraphQL Spec, https://spec.graphql.org/June2018/#sec-Overview

I’m not going to give you a history lesson on GraphQL and how it has come to coincide along REST. Honestly, I couldn’t do it justice because I haven’t been in software long enough to really understand the impact it made on the industry. What I do know is how it affected the way I think about development, particularly backend development.

I learned about REST in college for a software engineering course, albeit from a very DIY way. We had to break into teams and design a “Twitter-like service”. Since the goal was to teach us how to work in a team to build an end-to-end solution, we had a lot of flexibility in our decisions (other than the general functionality defined by our professor acting as the product manager). Two product grooming meetings later (because the first one the class asked all the wrong questions and ended up promising to deliver a combined Facebook, Instagram, and Twitter clone in a few weeks), we had our requirements. We got to choose every part of our tech stack, even though by that point most of us were only vaguely familiar with a single language or two from previous classes, let alone entire frameworks, databases, and the interactions between them. So like every good engineer, we used Google.

I was already in an internship at the time and was getting fairly familiar with JavaScript. This lead us to at least decide on Node.js as our API layer. Full disclosure, we had no idea what we were doing at the time, so I say “API layer” but that’s not what we knew it as at the time. We were basically just following tutorials we found and piecing them together to form something cohesive. You know, learning software development. We stumbled upon the MEAN (Mongo, Express, Angular, Node.js) stack and ran with it, partly because we found a good tutorial on scotch.io at the time. Also, like every four person college project, at least one person ended up contributing very little. I ended up writing a majority of the backend, which is where I learned REST.

REST was fairly simple then because I wasn’t using any complex frameworks (which would provide lots of functionality, but gloss over some key concepts and nuances I would never learn). I didn’t know what I was doing, especially when it came to middleware, but figuring out the Request and Response objects was kind of exciting. It definitely took me longer than I’d care to admit now, but wrapping my head around a simple REST API wasn’t too bad. I wouldn’t go on to learn much about enterprise REST API development in my job out of college (which was a bit of a regret/shame), but fast forward a few years to starting my current role at a startup company, and I would learn an entirely new way of developing a backend API. You guessed it, GraphQL (that was kind of cheesy and anti-climactic right?).

For me, GraphQL has always felt elegant. Right out of the gate, having a defined schema that the backend promises to abide by and the frontend understands what is available just makes so many conversations around data contracts that much easier. It also has always helped me with debugging. The schema validation will quickly tell you which side of an application isn’t following the schema. This already cuts your debugging landscape of an issue in half. When adding a new field or small feature to an object, just being able to add a single resolver function for that just feels simple and composable. You don’t have to deal with req and res objects, just (obj, args, context, info). These are basically always the same, whereas middleware can affect your req object (yeah it looks more complicated, but doesn’t feel that way to me). This also allows you to contain your data mapping layer closer to the database. Rather than having frontend controllers that do data mapping, you can agree on the data the frontend needs in the schema, and the backend will do the work. This leads to a more complex backend (technically, but I don’t find it that much more complex), but a simpler frontend. Where I find this adds value is in building teams. More senior engineers can focus on the complexity of solving problems on the backend, while more junior engineers can focus on using the data to display what design and product are asking for on the frontend. The frontend already has enough to worry about with getting all of the design right with CSS (a language I still don’t fully understand), let alone also needing to worry about mapping the data into a more usable format. Coincidentally, this data mapping and schema also makes the API more discoverable and friendly to API users with the GraphQL Playground.

Man, this guy can really get on his soapbox and ramble.

— All of you reading this

Don’t get me wrong, there are always tradeoffs to different tools that solve similar problems. I won’t go into all of those in this article because honestly, I haven’t ran into them. I don’t yet know all of the problems that GraphQL has a harder time solving than REST (the N+1 query problem being the most common, but Dataloader helps solve that). I know long-running operations is something that gets mentioned, but I haven’t had to solve for that yet (though I have ideas for how I’d do it that don’t really seem that difficult, but admittedly more effort than traditional REST). These have been acceptable from my perspective, and maybe I’ll run into a case where the tool doesn’t solve the problem. Great, then I’ll use a different tool. I’m not suggesting that GraphQL is “the answer to everything” because that would be naïve, but everyone has tools they prefer, and I think this one will stay near the top for me for awhile (especially as I start exploring more of the ecosystem of frameworks that are offered like Envelop from The Guild, which you should check out).