GraphQL: The next generation of API design

A look at misconceptions about GraphQL, coming from a REST background

This post was written as a response to Kin Lane’s post, “GraphQL Seems Like We Do Not Want To Do The Hard Work Of API Design.” Since then, Kin has published a follow-up, “I Am Keeping My Mind Open And Looking Forward To Learning More About GraphQL”

I sometimes hear people talk about how GraphQL is too complicated to be a good replacement for REST. I strongly disagree, and felt it would be useful to present an alternative point of view on the topic.

APIs are a core building block of the Internet as we know it, and the methods by which different services interact enable a lot of the information sharing and gathering we have come to take for granted. It’s important that the technologies with which we build and use APIs are as helpful and simple as possible.

A little background: I have always identified as a frontend developer — a person primarily interested in delivering great products to people and sweating the details of user experience, interactions, and performance. I’ve never written a database or a high-performance messaging system, and other than an academic interest, I’m not particularly knowledgeable about how they work.

I’m a frontend developer. GraphQL makes my life easy.

This post caught my eye because it seemed like a great way to analyze how people familiar with other kinds of APIs might respond to an initial look at GraphQL, and the misconceptions that might make it seem like an overly complex solution to a simple problem. But, as anyone who has spent a lot of time working with APIs will know, getting the right data to the right place (with any technology) can be anything but simple.

GraphQL is a query language, like SQL?

GraphQL seems like the numerous TEXTAREAS I’ve deployed behind the firewall to allow trusted users to write SQL to get at the database — which is just poking a hole, not very evolutionary at all.

While GraphQL looks like a query language at first, I think its name might be one of the things that gets people off on the wrong foot. GraphQL is not at all like SQL:

• You don’t connect GraphQL directly to your backend or database. It’s an API layer, just like REST.
• GraphQL intentionally doesn’t include built-in filtering, sorting, computations, or joins. You carefully design all of those yourself to fit the needs of the API consumer, just like REST.
• GraphQL can be layered over multiple backends and databases, without the client being aware of where the data is coming from, just like REST.

So GraphQL is a “query language” just like URLs are the “query language” of REST—it’s a contract that describes how to tell the API server what you’re looking for.

GraphQL is too hard?

It seems like you would attract 5 very technical API developers who would love it, but then exclude 5 non-technical users.

This is a very real concern whenever a new technology is introduced. Is this going to make stuff more complicated for everyone who isn’t in the know? Will it exclude people who don’t care about the finer points of graphs, nodes, and edges?

But the best part about GraphQL is exactly this point: It’s built from the ground up to make life easy for people who are trying to query it.

• It’s the only API platform that comes with a fully-featured data explorer out of the box (GraphiQL). People who use technologies like Firebase are often excited about how easy it is to explore their data directly from a dashboard. GraphQL is intentionally designed to enable tools like this, and GraphiQL is only the beginning.
• Even though you can easily send a GraphQL query with curl — no special tools needed — you don’t have to worry about the details of HTTP. Once you learn the language of GraphQL, you’re done. People often like to say that REST is “just HTTP”, but it turns out HTTP is not that simple — you have to know which method (GET? POST? PUT? PATCH? DELETE? can I even call these from my browser?) to use for each endpoint. You need to have some way of identifying which query parameters can be passed in the URL, and how they need to be serialized to avoid errors with special characters.
• GraphQL always returns what you expect. Depending on how principled the REST API you’re calling is, it could give you back basically anything for every request. In GraphQL, you’ll never be surprised by what you get back from the server.

There are a whole lot of companies out there with a whole business model of helping you describe your REST API and make it easier to get started with, because the base technology doesn’t provide these tools. To me, that’s the ultimate mark of a great tool — the language you use to interact with GraphQL is something you actually want to use directly (once you get used to it, of course), rather than immediately hiding it under layers of client abstractions.

If you want to try out writing some GraphQL queries, check out https://learngraphql.com/.

This is just the beginning

GraphQL feels like a quick fix to me and not one that looks to the future

The most exciting thing to me is that GraphQL has been publicly available for barely more than a year, and already a huge number of people I respect for their technical abilities and design thinking are trying to figure out ways to add it to their architecture. Part of the reason is that Facebook has been using it internally since 2012, so they’ve had a lot of time to iron out the kinks.

We’ve only scratched the surface of where it can go and how its clean, standardized way of describing and querying APIs can revolutionize data sharing on the internet. We’ve only seen one or two great tools extracted from this absolute gold mine of possibilities. Where REST was an ad-hoc philosophy that spawned many incompatible ways to describe, build, and consume APIs, GraphQL is a well-specified standard designed from the ground up to enable people to easily describe, understand, and retrieve their data with a shared language.

That’s why we spend so much time at Apollo doing our best to bring GraphQL to its full potential. I hope the above has started to convince any newcomers to the technology that it’s not all just a waste of time.