GraphQL vs REST: When to Use Which#

REST has been the default for APIs since 2000. GraphQL, created by Facebook in 2012, offers a different model. Neither is universally better — the right choice depends on your use case.

The Core Difference#

REST: Multiple endpoints, server decides the response shape.

GET /users/123          → { id, name, email, avatar, bio, ... }
GET /users/123/posts    → [{ id, title, body, ... }, ...]
GET /users/123/friends  → [{ id, name, ... }, ...]

Three requests. Each returns everything the server decides.

GraphQL: One endpoint, client decides what it needs.

query {
  user(id: 123) {
    name
    avatar
    posts(limit: 5) { title }
    friends(limit: 3) { name }
  }
}

One request. Client gets exactly what it asked for.

REST Strengths#

Simplicity#

Everyone knows REST. HTTP verbs map to CRUD:

• GET = Read
• POST = Create
• PUT/PATCH = Update
• DELETE = Delete

No special tooling needed. curl works out of the box.

Caching#

HTTP caching works naturally:

GET /users/123
Cache-Control: max-age=3600
ETag: "abc123"

CDNs, browsers, and proxies all understand HTTP caching.

GraphQL? Everything is POST to one endpoint. Caching requires extra tooling (Apollo Cache, Persisted Queries).

File Uploads#

REST handles multipart/form-data natively. GraphQL needs workarounds or a separate upload endpoint.

Predictable Performance#

Each endpoint has a known cost. Easy to rate limit, monitor, and optimize per route.

GraphQL Strengths#

No Over-fetching#

REST returns everything:

GET /users/123
{ "id": 123, "name": "Alice", "email": "...", "bio": "...", "avatar": "...", "created_at": "...", "settings": {...}, ... }

Mobile app only needs name and avatar — the rest is wasted bandwidth.

GraphQL returns exactly what you request:

{ user(id: 123) { name, avatar } }

No Under-fetching#

Need user + posts + friends? REST = 3 requests. GraphQL = 1 request.

Strongly Typed Schema#

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

Self-documenting. Clients know exactly what's available. IDE autocomplete works.

API Evolution#

Add fields without versioning:

type User {
  id: ID!
  name: String!
  email: String!
  avatar: String     # new field — old clients don't request it
  premium: Boolean   # another new field — zero breaking changes
}

Deprecate with @deprecated:

type User {
  name: String!
  fullName: String @deprecated(reason: "Use name instead")
}

Common Problems#

GraphQL N+1 Problem#

query {
  posts {       # 1 query: SELECT * FROM posts
    author {    # N queries: SELECT * FROM users WHERE id = ?
      name
    }
  }
}

Fix: DataLoader (batches N queries into 1):

-- Instead of N separate queries:
SELECT * FROM users WHERE id IN (1, 2, 3, 4, 5)  -- 1 batched query

GraphQL Security#

Clients can craft expensive queries:

query {
  users {
    posts {
      comments {
        author {
          posts {
            comments { ... }  # deeply nested, expensive
          }
        }
      }
    }
  }
}

Fix: Query depth limiting, query complexity analysis, persisted queries.

REST Versioning#

/api/v1/users  → old format
/api/v2/users  → new format (breaking change)

Maintaining multiple versions is expensive. GraphQL avoids this with additive changes.

Decision Framework#

Quick Decision#

• Public API (Stripe, Twilio style) → REST
• Mobile app with varied screens → GraphQL
• Internal microservices → REST or gRPC
• Dashboard with complex data needs → GraphQL
• Simple CRUD app → REST
• Multiple frontend clients (web, mobile, TV) → GraphQL

Architecture Patterns#

REST Microservices#

Mobile App → API Gateway → User Service (REST)
Web App                  → Product Service (REST)
                         → Order Service (REST)
                         → Payment Service (REST)

GraphQL Gateway (Federation)#

Mobile App → GraphQL Gateway (Apollo Federation)
Web App         → User Subgraph (owns User type)
                → Product Subgraph (owns Product type)
                → Order Subgraph (owns Order type)

Each subgraph owns its types. Gateway composes them into one unified schema.

Hybrid: REST + GraphQL#

Public API → REST (simple, cacheable, documented)
Internal Dashboard → GraphQL (complex queries, rapid iteration)
Service-to-Service → gRPC (fast, typed, binary)

Most companies use multiple protocols. Pick the right one per use case.

Generate your API architecture →

Tools#

Consider tRPC#

If your frontend and backend are both TypeScript, tRPC gives you end-to-end type safety without GraphQL's complexity:

// Server
const appRouter = router({
  getUser: publicProcedure.input(z.string()).query(({ input }) => db.user.findUnique({ where: { id: input } })),
});

// Client — fully typed, no codegen
const user = trpc.getUser.useQuery("123");

Summary#

1. REST is the safe default — simple, cacheable, well-understood
2. GraphQL shines with multiple clients and complex data needs
3. gRPC for service-to-service (fast, typed, binary)
4. tRPC for full-stack TypeScript (simplest typed API)
5. Hybrid is normal — most companies use REST + GraphQL + gRPC
6. Don't switch to GraphQL for the hype — switch when you feel the pain of over/under-fetching

---

Design your API architecture at codelit.io — REST, GraphQL, or gRPC. Generate interactive diagrams with 29 export formats.