REST API downfalls, and dawn of GraphQL

And getting started with GraphQL today

The world of software moves fast. Software developers and architects are always trying to balance simplicity vs. complexity; optimization vs. get-it-done; better-mousetrap vs. tried-and-tested.

Most of us thought (or still think) we had a good thing going with REST. Unlike earlier web service specs like SOAP and RPC, REST is simple. It’s based on universal web technologies (HTTP) and can be easily consumed by a javascript app (using JSON). It’s easy to grok, test, and debug (using a tool like Postman).

So why throw away a good thing? Simplicity is a good, but the simplicity of REST is also its downfall. REST grew up in an age where the server dominated the web application landscape.

While just a few years ago most websites used to be rendered on the server and have only relatively little client-side logic, the opposite is true of new apps today. Single-page applications and clients that implement complex logic are the new reality. (from GraphQL vs. Falcor article)

What’s wrong with REST?

With REST, the server determines what data will be sent down to the client. Each endpoint (URL) is supposed to simply represent a certain resource, for example a user or a blog post, or perhaps a collection thereof. If you need two different views of the same object (for example summary and detail views), you have to make two separate endpoints. At first this seems ok, maybe you have to create a few extra endpoints to accommodate different views in your client, no big deal.

But there’s another problem. Picture this: You built the initial prototype and now your app is becoming more complex, with different UI components on the same page. Each component gets its own data from a certain API endpoint, which makes your code elegant and simple. But now your customers complain that the app is slow. You realize you are making five different API calls in order to display a certain important page in your app. A simple solution is to create a new endpoint that aggregates all this data and delivers it in a single response. You also have to refactor your client to make this API call at the top level and pass the data down to the respective UI components. It feels like kind of a hack, but it works.

Your app continues to evolves and new requirements crop up. Maybe you have a dynamic table that the user can customize, with many possible fields to choose from. Another quick hack lets your client pass a list of fields to the server.

One day you wake up and you realize your server code has grown into a large mess of spaghetti. Perhaps worst of all, because you have multiple clients using your API out in the world, you’re afraid of eliminating any old code. REST has no versioning mechanism, so every time you refactor your server code and your data schema, you have to be mindful that there will be old clients that will still require the data in the old format (at least for a while). So the easiest thing is to do create new endpoints and leave the old ones untouched.

Playing with spaghetti is fun, sometimes

Is there a better way?

This is the question that developers at Facebook and Netflix asked that led them to creating new technologies like GraphQL and Falcor.

Netflix redid Falcor’s original logo because they felt it hindered early adoption

The basic premise of both GraphQL and Falcor is that the server exposes a comprehensive data schema to the client, and the client decides exactly what it needs. Unlike with discrete REST endpoints, all the data for any given UI (page) can be sent in one trip to the client.

Ultimately, GraphQL is the more flexible and complete solution of the two, while Falcor provides out-of-the-box simplicity and is GraphQL-like.

This great image from the article GraphQL in the age of REST APIs shows clearly how GraphQL differs from a REST API: