GraphQL vs REST API: what's the difference?
Which one should you use?

If you're building or scaling a modern web app with a backend, chances are you've come across GraphQL and REST APIs. As a freelance developer, I've worked extensively with both; and while each has its place, understanding when and why to use one over the other can save you hours of frustration and set your project up for success.

Let's break it down.

REST API: the traditional approach

REST (Representational State Transfer) has been around for a long time. It's simple, familiar, and follows standard HTTP methods like GET, POST, PUT, and DELETE. Data is usually sent and received in JSON, and each endpoint returns a fixed structure.

Pros:

• Easy to implement and widely supported.
• Great for simple, CRUD-style applications.
• Caching is straightforward with HTTP.

Cons:

• Often over-fetches or under-fetches data.
• You need multiple endpoints to get related data.
• Tight coupling between frontend needs and backend structure.

GraphQL: a smarter way to query

GraphQL flips the script. Instead of multiple endpoints, you get a single endpoint and a query language where you ask for exactly the data you need. Nothing more, nothing less.

Pros:

• Efficient: Only fetch the data you want.
• Flexible: Ideal for complex apps or mobile environments.
• Powerful developer tools.

Cons:

• Steeper learning curve if you’re used to REST.
• Requires more setup and tooling.
• Caching is more complex (though doable).

Real-world example

Say you want to show a blog post with the author's name and recent comments.

In REST, you might:

• Fetch the blog post at /posts/123
• Fetch the author at /users/456
• Fetch comments at /posts/123/comments

That's 3 separate requests; and you might still end up with data you don't need.

With GraphQL, you’d write one query like:

post(id: "123") {
  title
  content
  author {
    name
  }
  comments {
    text
    user {
      name
    }
  }
}

One request. One response. Exactly the data you need.

When to use REST or GraphQL