Why You Can't Replace REST With GraphQL

When I Googled “what is GraphQL” to learn more about the network protocols, all I saw was a comparison between REST and GraphQL. Most of the conclusions said, “use GraphQL.” It felt very binary (and trendy, for that matter), which is a problem because each product and use case is unique. The fact is, whatever is newest and shiniest gets recommended more loudly. But you have to weigh the trade-offs and come up with a solution that is best for your situation. 

There is a general understanding that either REST is better than GraphQL or vice versa. But the truth is they both address different problems and have different strengths and weaknesses. The question isn’t necessarily which one is better to use, but which one is better to use for specific circumstances. The best way to evaluate GraphQL, REST, or any other technology is to figure out your constraints based on the problem you are going to solve.

REST is a familiar option that can be implemented quickly. It is the popular option, and for good reason: it’s quick to learn and implement. No one wants to write complex code if they don’t have to, so it’s not hard to see why quick and easy REST beats complex and clever GraphQL in most situations.

Two aspects of REST really shine. The first is that most ORMs (object-relational mapping) are optimized to work with REST, so that is not a problem you will have to solve. The second is REST is ideal for quick transactional requests.

Additionally, with REST, you share the complexity between client and server. It has the benefit of proven patterns on how to do something, and it is definitely a well-proven, time-tested way of writing applications.

GraphQL is a different approach entirely, and it takes time and effort to create harmony. A system that is ideal for all your use cases will demand a lot of your time and will require your team to learn a lot of new concepts. It will force you to think in a certain way.  The cost of implementing GraphQL was probably going to be exhaustive — the move is not going to be a do-it-once-and-forget-it thing.

The default option would be REST, and it’s a good one. Not just because it’s easy, but because there is an expectation of shared familiarity. Developers are likely to already know REST, whereas the same is not true for GraphQL. Unless you’ve identified needs that GraphQL is especially good at solving, REST is the default choice for a good reason. We would rather rest easy with REST, build something that both excites and helps our users and get their product in the hands of their friends and family with time-tested methods.

REST vs. GraphQL

Let’s get right into it. With REST, there’s a lot of back and forth and manual work. Calls can result in either over-fetching or under-fetching based on the API contract. For example, if you end up with URIs (uniform resource identifiers) and not the specific data you’re looking for, the network calls you need to make on your client to get what you need to escalate quickly.

Whereas GraphQL gets exactly the data you want on an API call. You have control over the query on a granular level, which is not something you can not easily do with REST since it’s not made for that specific purpose. Having this granular control will allow you to have fewer network calls and will require fewer developmental changes on client applications since responsibility has been shifted to backends.

Applications can be informationally and visually heavy and also need to retrieve a variety of interconnected data. Fewer network calls in this scenario can be crucial for performance when this data needs to be retrieved in what are potentially many different and unknown situations. With the right implementation of GraphQL, you can eliminate the ability to over-fetch.

If your application is reading 1MB of data locally, it can finish the job in 0.4 milliseconds — as opposed to reading it over the network, which can take 150 milliseconds — a drastic difference. The point here is you want to optimize for fewer network requests. REST doesn’t give you those affordances. If optimizing for network requests is the most important factor, GraphQL would work better for you.

With GraphQL, you’ll get only the information you need. This is due to a self-documenting schema that’s easier to consume and has better tooling around consuming your endpoint.

GraphQL Is More Than Just Making Queries

Writing GraphQL queries is just the tip of the iceberg. Implementing a brand new solution with GraphQL comes with challenges to overcome and problems to solve. The GraphQL stack might appear to be simple to get started with, but it gets complex quickly. It requires a lot of upfront learning and can be intimidating for newcomers to figure out how all these pieces fit together. Before you move to GraphQL, you need to understand what you’re signing up for.

Since GraphQL is not built into an ORM, it means there’s a lot of architectural choices that need to be made for your stack that will require extra effort to set up. It also comes with a steep learning curve. Part of that learning curve is actually control. GraphQL inverts control and hands it over to the client. Any amount of information can be requested, which means building a third-party API can become burdensome if you have expensive queries.

We all know naming things is hard, and GraphQL makes this a little harder. The GraphQL schema is a list of object types. It’s more than just a catalog; it’s a snapshot of the API. In a very large codebase, this could lead to naming collisions, so thoughtful naming conventions are a must.

In addition to the learning curves we’ve found ourselves dealing with, caching, one of the most loved and hated topics in computer science, is a whole lot more adventurous with GraphQL. Caching can happen on the client or on the server. REST uses headers to control the caching. However, GraphQL doesn’t have this affordance at the HTTP level.

All POST requests in GraphQL automatically opted out of the free HTTP caching you get in the browser. That means you have to bring your own cache when you’re in GraphQL land. Not only is this caching solution something you have to build, but you also have to maintain it — a consideration that should be thought about thoroughly.

In the end, you want to build something useful. GraphQL and REST can get you there, but be mindful about what either option means for you and your team long term. 

The REST and GraphQL Partnership

The general wisdom is to choose either REST or GraphQL for your needs, but in reality, neither one covers all the bases. The biggest motivation when building something should be to evaluate how a developer would like to use it. Start gradually with introducing GraphQL first in the internal APIs and converted these endpoints to see how they work internally before exposing them externally.

However, for the studio application, GraphQL is the better choice. Even though REST would allow you to build it, it isn't necessarily the best solution. It would require you to either implement (or add more) logic to handle new information and endpoints every time you decide to have new info on a page. Because the application has a growing need for data and information, and GraphQL solves this problem better.

The backend data objects and business objects are rapidly becoming more interconnected, and GraphQL is a good way to relate each business object within the ecosystem. Managing all that in REST would be quite a task. And it comes with the downside of additional network requests.

GraphQL solved these constraints fairly well. So while conventional wisdom states you should move to GraphQL entirely, the fact is, for customer-facing APIs, you need REST. For business-centric frontends, however, GraphQL is the answer.

So What’s Right for You?

GraphQL is an exciting field — with a learning curve! But once you get the hang of it, specifications provide out-of-the-box tooling and saves a lot of code. Finding the balance between getting features out the door and adopting new technology can be a challenge. Finding the iterative approach that gives you time to adopt new technology would help you gradually increase your chances of success.

So there is no silver bullet that solves all the problems. New solutions are inspired by shortcomings in existing technology, but they come with new sets of challenges. Everyone’s situation is different, and contextualizing the solutions based on your problem space is the way to think when making these fun decisions.