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:

If you still need convincing on GraphQL, you may want to read Why GraphQL is the future for more convincing arguments.

Ready to go?

GraphQL is here and ready to go.

Seriously, you want me to introduce another new technology stack into my already-complicated life?

Yes. Why? Because it will make your life much easier in the long run.

So how do you use this thing? To get started you need a GraphQL server and and GraphQL client.

On the server side, GraphQL can be used with many different databases (you can even combine data from multiple databases into one GraphQL schema). This tutorial shows you how to build a GraphQL server that connects to a SQL DB and a MongoDB (and even a REST endpoint!)

On the client side, there are currently two competing GraphQL libraries. The official library from Facebook is called Relay, while the maverick upstart Apollo (from the same people that brought you Meteor JS) is not quite as far along, but promises more simplicity and flexibility.

If you want to see an example of how to use GraphQL for a web app, you may want to test out react-starter-kit or relay-starter-kit. For Apollo, take a look at the GitHunt full-stack example app.

To see an example of how to use GraphQL in a native mobile app (android and iOS, via react-native), you should check out the Facebook sample app called f8app. There is also a fork, f8app-apollo which uses Apollo (no promises on how complete this is).

Good luck on your GraphQL adventures, and beyond.

Author’s note: I’m currently available for hire and I suck at human networking. If you need help with GraphQL, React, or full-stack development in general, please get in touch, at gmail at vonwao.

Like what you read? Give Otto von Wachter a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.