REST vs GraphQL: Which to Choose for a Custom Project

Behind every modern web application, corporate dashboard, or e-commerce platform, there is an API (Application Programming Interface) acting as a bridge between the database and the user interface. For over two decades, the undisputed standard for building this bridge has been REST. In recent years, however, GraphQL (created by Facebook) has shaken up the industry, promising to solve many of REST’s historical limitations.

The result? Many teams choose GraphQL simply to follow the trend (the infamous Hype-Driven Development), ending up needlessly complicating projects that required simple solutions - the same risk I discuss when talking about Vibe Coding and its limits: the right technology is the one that fits the problem, not the one everyone is talking about.

To build custom software that stands the test of time, the choice of architecture must be purely pragmatic. Let’s analyze the real advantages of both approaches and the criteria to choose the right one.

REST: The Reliability of the Standard

A REST (Representational State Transfer) architecture is based on simple, universal concepts: you use specific URLs (called endpoints) to access certain resources (e.g., /api/users/123) and you use standard HTTP verbs (GET, POST, PUT, DELETE) to tell it what to do.

The real advantages of REST:

• Native Caching: This is its superpower. Because each resource has its own unique URL and GET requests are cacheable by default, browsers and CDNs (like Cloudflare or Netlify) can store responses by relying on standard HTTP headers (Cache-Control, ETag), drastically lightening the server load - the same principle I rely on when deploying a site on an Edge/CDN network to cut TTFB.
• Universal Simplicity: Any developer, from Junior to Senior, knows how to query a REST API. It doesn’t require special client-side libraries; a simple fetch() is all it takes.

The main limitations:

• Over-fetching: If you only need a user’s “First Name,” the REST endpoint will still return the entire object (first name, last name, email, birth date, order history). You download useless data, wasting precious bandwidth (especially critical on mobile networks) - a cost that adds to what I cover in how site speed impacts sales.
• Under-fetching: To display a complex dashboard, you might have to make 5 or 6 separate HTTP calls to different endpoints (e.g., /users, then /orders, then /invoices), slowing down page rendering.

GraphQL: Tailored Flexibility

GraphQL flips the paradigm. Instead of having dozens of endpoints, you have one single endpoint (e.g., /graphql). The client sends a structured Query asking for exactly the fields it needs, and the server returns a JSON object with that exact structure.

Here is the same scenario - a dashboard showing a user’s data, their orders, and their invoices - in both approaches:

// REST: 3 separate calls (and each response also carries fields we won't use)
const [user, orders, invoices] = await Promise.all([
  fetch('/api/users/123').then((r) => r.json()),
  fetch('/api/users/123/orders').then((r) => r.json()),
  fetch('/api/users/123/invoices').then((r) => r.json()),
]);

# GraphQL: 1 single request, only the fields we need
query {
  user(id: 123) {
    name
    orders { id total }
    invoices { number amount }
  }
}

The real advantages of GraphQL:

• Zero Over-fetching: Ask for 3 fields, get 3 fields. This makes client-side applications much faster and lighter.
• Frontend Agility: Frontend teams no longer have to ask the backend to create a new endpoint every time a page design changes. They can simply modify the query to request different data.
• Strong Typing: GraphQL uses a strict Schema Definition Language. The client always knows exactly what data is available and what type it is (String, Int, Boolean), drastically reducing miscommunication errors - an advantage that pairs naturally with the approach I describe in my article on TypeScript and scalable code.

The main limitations:

• More Complex Caching: GraphQL queries typically travel via POST to a single endpoint, so native browser and CDN HTTP caching is far less effective than with REST. To compensate, teams turn to techniques like persisted queries or normalized client-side caches, typically through libraries such as Apollo Client or Relay.
• The “N+1” Problem: If not configured by expert hands (e.g., using DataLoaders), GraphQL can inadvertently query the database hundreds of times for a single request, bringing the server to its knees.

Practical Criteria for Your Choice

There is no absolute winner. When I sit down with a client to design the architecture of a new application, I use these decision criteria - always before writing code, as I explain in the phases of a corporate software project.

Choose REST if:

• You are building a simple application or an MVP (Minimum Viable Product).
• The nature of your data requires strong HTTP caching (e.g., a public product catalog or blog articles).
• You have a limited budget for the initial infrastructure and want to maximize release speed without introducing steep learning curves.
• You need to interface with legacy systems or third-party services that expect traditional webhooks and HTTP calls.

Choose GraphQL if:

• You are developing a highly interactive application (like a social network, a project management tool, or an analytical dashboard) where multiple entities are heavily interconnected.
• The application will be heavily consumed by mobile devices on slow networks, where bandwidth savings and minimizing HTTP requests are crucial.
• You have multiple clients (Web, iOS, Android, Smartwatch) that require completely different views of the same data.

And in an Astro Site? This Very Site as an Example

To keep this grounded, here is what I actually use on this site - and what I don’t:

• No GraphQL, and no runtime API for the blog. Articles are Markdown files read at build time through Astro’s Content Collections: the site is entirely static, so there is no server or database to query on every visit. Forcing GraphQL here would be exactly the pointless exercise in style I mentioned at the start.
• A REST-style JSON endpoint with HTTP caching: /llms-full.json, the machine-readable knowledge base built for crawlers and AI agents. It’s generated once at build time and served with Cache-Control: public, max-age=86400 and open CORS (Access-Control-Allow-Origin: *). A practical detail: Astro discards custom headers on prerendered endpoints, so they have to be declared at the CDN level, in netlify.toml - it’s precisely the native HTTP caching I described in the REST section, working here at zero cost.
• A plain POST for the contact form: an ordinary fetch("/", { method: "POST", ... }) to Netlify Forms, with no libraries or dedicated client.

Three real examples, three minimal solutions: for a project with these needs, the simplest possible solution is also the right one.

Conclusion

The best technology is always and only the one that solves the business problem most efficiently. Forcing GraphQL into a static blog is a pointless exercise in style, just as using REST for a real-time financial dashboard risks creating an unsustainable bottleneck. Thoroughly analyzing the data structure and expected user behavior before writing the first line of code is the only way to ensure your software investment scales seamlessly - the same philosophy behind choosing between a custom-coded site and a CMS like WordPress.