GraphQL vs. REST: Which is best?

Written by: John Hurd

GraphQL and REST APIs are both powerful tools to let users and programs access information. 

But how do you decide between the two? What kind of projects would be better solved by a GraphQL API? What about a REST API? 

In this article, we’ll provide a framework to help you decide between GraphQL vs. REST APIs.

After reading this article, you’ll understand some key differences between GraphQL and REST, what factors to consider when choosing between GraphQL and REST APIs, and the strengths and weaknesses of the two technologies.

Summary of when to choose GraphQL vs. REST

We’ll use the FURPS framework to consider the essential differences between GraphQL and REST.

FURPS is a software development framework that stands for Functionality, Usability, Reliability, Performance, and Supportability. It’s designed to enumerate critical aspects of any software decision so you can make the best decision for your use case and context.

Within each category of the FURPS framework, we’ll focus on one or two specific categories that are particularly relevant to APIs.

Here’s a quick breakdown of the key differences between GraphQL and REST:

5 factors to consider when choosing between GraphQL and REST APIs

Before we jump in, it’s important to acknowledge a few things:

• The FURPS framework isn’t the only tool you can use to systematize your decision—we just think it’s the most comprehensive and applicable to this particular decision.
• Not a fan of frameworks? No problem! The factors described below can be considered outside the context of a framework and still be helpful.
• The list of factors we’ll discuss is not exhaustive—there are others you could consider when choosing between GraphQL and REST, but we’ll discuss the most critical ones.

So, let’s dive in!

1. Functionality

Data structure

The first thing to consider is the structure of the data you’re accessing. 

GraphQL is well-suited for highly nested, complex, and hierarchical data. 

An example where GraphQL would be a good choice is an e-commerce platform that displays dynamic product pages where each user customizes their view to see only what they want on each page. 

GraphQL is a good choice here because it allows you to make a query to get only the data that needs to be shown to a given user. 

Another example where GraphQL shines is a social media site with complex, nested relationships. Because GraphQL can perform nested queries, it can access the necessary data efficiently in a single query.

REST is well-suited for data with obvious access patterns, well-defined schemas, and relatively simple relationships. 

A public news API is an example where REST would be a great choice. You could create endpoints for all topics covered by the news (e.g., news/sports and news/politics) that can cache and serve data efficiently and consistently to each client. 

Endpoints for a mobile banking app are another example where REST’s simplicity and consistency shine. REST would be a great choice here because the endpoints are well-defined (they don’t require custom queries for each user) and won’t change frequently.

Security

Security is a critical consideration when designing and protecting an API. It protects the data being served and prevents misuse from illegitimate requests that could crash your system.

Two common methods to secure an API are:

• Access controls
• Rate limits

GraphQL allows for very fine-grained security access controls. This can be helpful in scenarios where different users need access to different subsets of a larger dataset. 

But these fine-grained access controls come at a cost—managing access controls can be tricky and require more thought than a REST API. 

Rate-limiting access with GraphQL is also a bit more complex and nuanced than a REST API. It usually involves depth or field-based rate limits or a token-based rate limit for specific, complex operations.

REST APIs have clearly defined endpoints that all users access, so applying security controls and rate limits is typically straightforward. This simplicity makes REST a more manageable option for implementing, testing, and maintaining security measures. 

2. Usability

Learning curve for new users

It’s important to consider who is using your API and how easy it will be for the average user to accomplish common goals.

GraphQL queries are more flexible but also more complex. So it will be harder for new users to get the information they want from a GraphQL API.

REST queries are simpler and more general, making it easier for new users to figure out how to get the data they need. 

One caveat here is that API design plays a huge role in determining how easy it is to get the relevant data. If users consistently have to make multiple requests to get the data they need for common use cases, this increases the complexity of using the endpoint. 

When designing an API, make sure the structure is sensible and will support common use cases.

As you consider this topic, there are several fun ways to engage new users and reduce their learning curve. You can also use a tool like ReadMe to make it easier for new users to learn how to use an API through interactive documentation and an AI chatbot that can answer users’ questions based on your documentation.

Tooling and community support

GraphQL is a newer technology with a rapidly growing ecosystem of tools such as the Apollo Client, GraphQL Playground, and Hasura. 

The community is generally very active and innovative, and it usually focuses on solving problems related to security, query optimization, schema management, and introspection.

REST is an older technology with broad, battle-tested support. Tools like ReadMe, Postman, OpenAPI, and NGINX make API design, testing, and deployment straightforward.

The community also has an extensive library of resources for authentication, caching, and monitoring. REST’s maturity in the industry ensures a reliable, well-documented ecosystem, making it easy to find support and integrations for nearly any tech stack.

An example of the powerful tooling surrounding REST APIs is ReadMe’s SDK generator, api, which automatically creates custom SDKs from an OpenAPI definition. (It’s open-source and really cool, so you should check it out if you use OpenAPI.)

3. Reliability

Error handling

GraphQL can query multiple resources in a single request. Because one of those queries may fail while the others succeed, GraphQL supports returning partial failures if a subset of the queries fails.

GraphQL usually returns errors in an errors array with detailed information about which parts of the query failed. This is convenient because you can still get any data that was successfully queried, but query results may not be as consistent as a REST API.

REST error handling is all-or-nothing. Either you get all of the data you asked for or none at all. This ensures the API returns consistent data, but it may hurt API availability if the API is querying an unavailable resource.

REST uses standard HTTP status codes to communicate the outcome of a request, making it relatively easy to handle errors in user interfaces. Helpful error messages are also essential to help requesters debug any issues that come up.

4. Performance

Speed and caching

GraphQL generally requires fewer network requests with more complex and customized queries than REST.

Because of this, GraphQL can avoid the network delays sometimes incurred by multiple requests to different REST endpoints. That said, GraphQL queries usually take longer for the datastore to process and are difficult to cache because they are so flexible and customizable.

REST queries are generally simpler but may require more network requests.

Depending on their design, REST APIs may give you more data than you need (over-fetching) or less data than you need (under-fetching). If this happens, you’ll have to make another request.

This means you might make more network requests to a REST API than a comparable GraphQL API, but each query will usually be easier for the datastore to process.

Another thing to keep in mind is that the consistency of a REST endpoint allows you to cache data to speed up response times and reduce load on your datastore.

5. Supportability

Versioning

The last aspect we’ll consider is the way updates and new versions are released in GraphQL vs. REST.

GraphQL typically avoids explicit versioning by encouraging schema evolution. This means you make additive changes, such as adding new fields or types, without removing existing ones. 

Clients can request only the fields they need—which reduces the need for multiple versions and enables gradual deprecation of outdated fields. 

While this flexibility means you only have to manage a single API version, it does require you to carefully manage your schemas to ensure backward compatibility. Schema changes often require documentation to keep clients informed about new and deprecated fields.

REST traditionally uses explicit versioning to manage breaking changes, often in the URL path (e.g., /api/v1/resource). This clear versioning structure makes it easy for clients to know which version they interact with, enabling stable interfaces and easier migrations. 

However, maintaining multiple versions can increase development and maintenance overhead, especially if multiple versions need simultaneous support. REST’s explicit versioning can become cumbersome if older versions aren’t deprecated effectively as APIs grow and evolve.

To learn more about managing API versions effectively, check out our guide to documentation versioning in ReadMe.

Use the FURPS framework to help you find the best solution to your challenge

GraphQL and REST are both great tools! Deciding which one to use can be difficult as it will have a substantial long-term impact on everyone using the API. 

The FURPS framework and the subcategories detailed above will help you decide which tool you can scale, support, and maintain most effectively.

One pitfall we’ve seen is that technology decisions like this are made solely based on engineers’ preferences.

While the preferences of engineers creating (and, perhaps, using) the API can be informative, it’s always important to dig deeper and understand why engineers prefer one solution over another. Bonus points if you can fit engineer feedback into the FURPS framework!

Deciding when to use GraphQL vs. REST APIs should be carefully considered and driven by the business and user needs relevant to a given project.

Whether you choose REST or GraphQL, ReadMe can help you create a developer hub with interactive documentation to get users up and running on your API. ReadMe supports REST APIs at over 6,000 companies and also supports GraphQL APIs. (Reach out to [email protected] for more details.)