GraphQL vs REST: When to Choose Each and Why It Matters

Introduction

GraphQL vs REST is one of the most common debates in modern API development — and by the end of this article, you will know exactly which one to choose.

In our previous articles, we explored SOAP, REST, and even built a RESTful API with Python and Django REST Framework. As a result, we saw how REST replaced SOAP as the dominant style for web services. Its simplicity, statelessness, and use of standard HTTP methods made it the natural choice.

However, the story of APIs did not end with REST. In 2015, Facebook open-sourced a technology called GraphQL. Since then, one question keeps appearing in technical discussions and architecture meetings: should I use REST or GraphQL?

In this article, we will go beyond the basics. First, we will understand why GraphQL was created and which problems REST could no longer solve. Then, we will compare how each approach works in depth. After that, we will look at famous public APIs that use each one. Finally, I will share the books you should read to master both technologies.

1. A Quick Recap: What is REST?

As defined in our previous article, REST (Representational State Transfer) is an architectural style for networked applications. Roy Fielding introduced it in his doctoral dissertation, “Architectural Styles and the Design of Network-based Software Architectures” (Fielding, 2000).

In short, REST defines a set of constraints to achieve performance, scalability, and simplicity:

• Client-Server: separation between user interface and data storage;
• Stateless: each request contains all the information needed to process it;
• Cacheable: responses must define themselves as cacheable or not;
• Uniform Interface: resources have URIs and use standard HTTP methods (GET, POST, PUT, PATCH, DELETE);
• Layered System: the architecture can be composed of hierarchical layers.

Since the 2000s, REST has been the industry standard. In fact, according to Postman’s State of the API Report, it remains the most used style among developers today (Postman, 2023).

So, if REST works so well, why did Facebook feel the need to create something new?

2. The Problem: Why REST Was No Longer Enough for Facebook

To understand GraphQL, we need to go back to 2012. At that time, Facebook was rebuilding its native mobile applications, and the context matters:

• Smartphones were becoming the main way people accessed the internet;
• Mobile networks (especially 3G) were slow and unreliable, above all in developing countries;
• Facebook’s data model was deeply interconnected: users have friends, friends have posts, posts have comments, and comments have authors.

Because of this context, the engineering team — led by Lee Byron, Nick Schrock, and Dan Schafer — faced three structural problems with REST (Byron, 2015).

2.1 Over-fetching

REST endpoints return a fixed data structure defined by the server. For example, when the mobile app requested GET /users/123, it received the complete user object: name, email, birthday, hometown, and work history. Yet the screen only needed the name and the profile picture. On slow networks, every wasted byte meant a slower experience. Moreover, it meant higher data costs for the user.

2.2 Under-fetching and the N+1 Requests Problem

The opposite problem also existed. To render the News Feed, the app needed data from several resources: the user, their posts, the comments, and the comment authors. Consequently, REST forced multiple sequential round trips:

GET /users/123 → get the user 
GET /users/123/posts → get their posts 
GET /posts/1/comments → get comments of post 1 
GET /posts/2/comments → get comments of post 2 
...

Each round trip on a 3G network added latency. As a result, the app felt slow and users became frustrated.

2.3 Endpoint Proliferation and Versioning

To work around these limits, teams often created custom endpoints for specific screens, such as /users/123/newsfeed-mobile-v2. Over time, this produced dozens of endpoints that were hard to maintain and document. In addition, every design change in the app required backend changes and new API versions.

GraphQL was born as a direct answer to these three problems. It offers a single endpoint where the client — not the server — decides exactly which data it needs, in a single request.

3. What is GraphQL?

GraphQL is a query language for APIs and a server-side runtime that executes queries against a type system (GraphQL Foundation, 2024). Facebook developed it internally in 2012 and used it in production from 2013. Later, in 2015, the company open-sourced it. Today, the GraphQL Foundation, hosted by the Linux Foundation, governs the project.

One important clarification: GraphQL is not a database technology. It has no relation to graph databases like Neo4j. Instead, the “Graph” in the name refers to how it treats your data as a connected graph of objects.

Here is a simple analogy. Imagine ordering food at a restaurant:

• With REST, you order from a fixed menu. You ask for “Meal number 3” and receive everything in it — whether you wanted all of it or not.
• With GraphQL, you build your own plate. You tell the kitchen: “I want rice, chicken, and salad” — and that is exactly what you receive.

3.1 The Schema: The Contract Between Client and Server

Everything in GraphQL starts with the schema, written in the Schema Definition Language (SDL). The schema is strongly typed and works as a contract:

type User { 
  id: ID! 
  name: String! 
  email: String!
  posts: [Post!]! 
} 

type Post { 
  id: ID! 
  title: String!
  content: String!
  author: User!
  comments: [Comment!]! 
} 

type Comment { 
  id: ID! 
  text: String!
  author: User!
}

The exclamation mark (!) means the field cannot be null. Thanks to this type system, we get powerful tooling: auto-completion, validation, and self-generated documentation.

3.2 Queries: Reading Data

A query is the equivalent of a GET in REST. However, the client specifies exactly which fields it wants:

query {
  user(id: "123") {
    name
    posts(limit: 3) {
      title
      comments(limit: 2) {
        text
        author {
          name
        }
      }
    }
  }
}

Notice what happened here. The entire News Feed problem from section 2.2 was solved in a single request. User, posts, comments, and authors — one round trip.

3.3 Mutations: Writing Data

Mutations create, update, or delete data. In other words, they are the equivalent of POST, PUT, PATCH, and DELETE:

mutation {
  createPost(title: "GraphQL vs REST", content: "...") {
    id
    title
  }
}

3.4 Subscriptions: Real-Time Data

Subscriptions let the client receive real-time updates from the server, usually via WebSockets:

subscription {
  newComment(postId: "1") {
    text
    author {
      name
    }
  }
}

3.5 Resolvers: Where the Logic Lives

On the server side, each field in the schema has a resolver — a function that fetches that specific piece of data. This is where GraphQL connects to your databases, microservices, or even existing REST APIs. In fact, a common migration strategy is to build a GraphQL layer on top of existing REST services.

4. GraphQL vs REST: In-Depth Comparison

Here is an honest observation. GraphQL solves the N+1 problem on the network side, between client and server. However, it can bring the same problem back on the server side, between the API and the database, if resolvers are written naively. For this reason, tools like DataLoader exist. Facebook created it to solve this issue through batching and caching (Facebook, 2015).

5. Famous Public APIs: Who Uses What?

Theory is important. Even so, seeing real-world adoption gives us a better perspective.

5.1 Famous Public REST APIs

• **Stripe API** — considered by many the gold standard of REST design. It offers predictable resources, consistent errors, and excellent documentation (Stripe, 2024). Therefore, if you want to learn REST design, study Stripe.
• Twilio API — communications (SMS, voice, WhatsApp) built entirely on RESTful conventions.
• GitHub REST API (v3) — one of the most used APIs in the world, available since 2011.
• Spotify Web API — music catalog, playlists, and player control via REST.
• OpenWeatherMap API — a classic for beginners learning to consume APIs.

5.2 Famous Public GraphQL APIs

• **GitHub GraphQL API (v4)** — the most emblematic case. In 2016, GitHub announced that its next-generation API would use GraphQL. The reasons were exactly the over-fetching and endpoint proliferation problems we discussed (GitHub, 2016). Interestingly, the same company still maintains both styles: v3 (REST) and v4 (GraphQL).
• Shopify Storefront & Admin APIs — Shopify adopted a GraphQL-first strategy for e-commerce. As a result, each storefront requests only the product data it needs (Shopify, 2024).
• **The Rick and Morty API** — a free GraphQL API with no authentication. It is perfect for study and practice.
• **Countries API** — another free GraphQL API, ideal for your first queries.
• AniList API — an anime and manga database, fully GraphQL.

Notice the pattern. Companies with complex, connected data and many client types (GitHub, Shopify, Facebook) gravitate towards GraphQL. On the other hand, companies with clear, transactional resources (Stripe, Twilio) remain successfully on REST.

6. When to Choose REST

Based on everything we analysed, REST remains the right choice when:

1. Your API is resource-oriented and CRUD-heavy. If your domain maps naturally to resources (tasks, users, products), REST’s simplicity is an advantage.
2. HTTP caching is critical. REST GET requests are cacheable by browsers, CDNs, and proxies. In contrast, this is very hard to replicate with GraphQL.
3. You are building a public API for third parties. REST’s universality lowers the entry barrier for external developers.
4. Your team is small or the deadline is short. There is no schema to design and no resolvers to write.
5. File uploads are a core feature. REST handles multipart/form-data natively.

7. When to Choose GraphQL

On the other hand, GraphQL becomes the better choice when its original problems are your problems:

1. Multiple clients with different data needs. For instance, a web app, a mobile app, and a smartwatch app consuming the same API — each requesting only what it needs.
2. Deeply interconnected data. If one screen needs data from 4 or 5 REST endpoints, GraphQL’s nested queries remove the extra round trips.
3. Mobile-first products on unreliable networks. This was Facebook’s original motivation. Furthermore, it is especially relevant in our African context, where mobile data is expensive and networks are inconsistent.
4. Fast-moving frontend teams. Frontend developers add fields to their queries without waiting for backend changes.
5. Real-time features in the same API. Subscriptions provide a standard model for live updates.

Finally, remember: the two are not mutually exclusive. A common architecture uses REST for authentication, webhooks, and uploads, while GraphQL handles complex data fetching. After all, GitHub itself maintains both.

8. Conclusion

GraphQL did not appear to “kill” REST. Instead, it appeared because Facebook’s reality in 2012 — mobile clients, slow networks, connected data — exposed real limits in the fixed-endpoint model: over-fetching, under-fetching, and endpoint proliferation.

REST remains an excellent choice. It is simple, cacheable, and universal, and it still powers most of the world’s APIs. Meanwhile, GraphQL is a specialized tool that shines when data complexity and client diversity justify its extra server-side cost.

Therefore, before choosing, ask yourself:

1. How interconnected is my data?
2. How many client types will consume this API?
3. How important is HTTP caching for my use case?
4. Can my team manage a GraphQL server responsibly (query complexity, N+1, security)?

The honest answer to these four questions will point you in the right direction.

Have you used GraphQL in production? Do you prefer REST? Share your experience in the comments — your feedback matters and helps make these articles better!

Thank you for reading!

9. Recommended Books

Before the formal reference list, here is my suggested reading order:

To study REST: start with Richardson and Ruby (2007), the classic that popularized REST; then move to Richardson et al. (2013), its modernized successor; and keep Massé (2011) as a practical design rulebook. For the theoretical foundation, read Fielding’s (2000) original dissertation.

To study GraphQL: start with Porcello and Banks (2018), the best entry point for beginners; then Wieruch (2018) for a practical, project-based approach; and finish with Giroux (2020), written by a former GitHub engineer, to learn how to run GraphQL at scale in production.

10. References

Byron, L. (2015, September 14). GraphQL: A data query language. Engineering at Meta. https://engineering.fb.com/2015/09/14/core-infra/graphql-a-data-query-language/

Facebook. (2015). DataLoader [Computer software]. GitHub. https://github.com/graphql/dataloader

Fielding, R. T. (2000). Architectural styles and the design of network-based software architectures [Doctoral dissertation, University of California, Irvine]. https://ics.uci.edu/~fielding/pubs/dissertation/top.htm

GitHub. (2016, September 14). The GitHub GraphQL API. The GitHub Blog. https://github.blog/2016-09-14-the-github-graphql-api/

Giroux, M.-A. (2020). Production ready GraphQL. Self-published. https://book.productionreadygraphql.com/

GraphQL Foundation. (2024). GraphQL documentation. https://graphql.org/

Massé, M. (2011). REST API design rulebook. O’Reilly Media.

Porcello, E., & Banks, A. (2018). Learning GraphQL: Declarative data fetching for modern web apps. O’Reilly Media.

Postman. (2023). 2023 state of the API report. https://www.postman.com/state-of-api/

Richardson, L., Amundsen, M., & Ruby, S. (2013). RESTful web APIs: Services for a changing world. O’Reilly Media.

Richardson, L., & Ruby, S. (2007). RESTful web services. O’Reilly Media.

Shopify. (2024). Shopify API documentation. Shopify.dev. https://shopify.dev/docs/api

Stripe. (2024). Stripe API reference. https://stripe.com/docs/api

Wieruch, R. (2018). The road to GraphQL. Self-published. https://www.robinwieruch.de/the-road-to-graphql-book/

Originally published at https://mariomthree.com on July 20, 2026.