GraphQL vs REST vs tRPC: Choosing the Right API Paradigm

┌─────────────────────────────────────────────────────────────┐
│                       tRPC                                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Core Principles:                                           │
│  • Type-safe API without code generation                   │
│  • Share TypeScript types between client and server        │
│  • Zero-schema API definitions                            │
│  • Works seamlessly with Next.js, React                    │
│                                                             │
│  Example:                                                   │
│  // Client code (fully typed!)                           │
│  const user = await trpc.user.getById.query("123")       │
│  // Knows exact return type without any setup             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# Feature comparison
comparison:
  data_fetching:
    rest:
      pattern: "Multiple endpoints"
      overfetching: "Often"
      underfetching: "Sometimes"
      n_plus_1: "Common problem"
    graphql:
      pattern: "Single endpoint"
      overfetching: "Minimal"
      underfetching: "No"
      n_plus_1: "Solved with dataloader"
    trpc:
      pattern: "Multiple procedures"
      overfetching: "Minimal"
      underfetching: "No"
      n_plus_1: "Your responsibility"
      
  typing:
    rest:
      types: "Manual or code gen"
      shared: "Requires setup"
    graphql:
      types: "Code generation"
      shared: "GraphQL Code Generator"
    trpc:
      types: "Automatic"
      shared: "Native TypeScript"
      
  learning_curve:
    rest: "Low"
    graphql: "Medium-High"
    trpc: "Low-Medium"
    
  caching:
    rest: "HTTP caching"
    graphql: "Client-side caching"
    trpc: "React Query integration"

rest_scenarios:
  - "Simple CRUD operations"
  - "Resource-oriented data models"
  - "When HTTP caching is important"
  - "Team is unfamiliar with GraphQL"
  - "Public APIs for external consumers"
  - "Microservices with clear boundaries"

// Express REST API
import express from 'express';
const app = express();

app.get('/api/users', async (req, res) => {
  const users = await db.user.findMany();
  res.json(users);
});

app.get('/api/users/:id', async (req, res) => {
  const user = await db.user.findUnique({
    where: { id: req.params.id }
  });
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }
  res.json(user);
});

app.post('/api/users', async (req, res) => {
  const user = await db.user.create({
    data: req.body
  });
  res.status(201).json(user);
});

graphql_scenarios:
  - "Complex data relationships"
  - "Mobile apps with limited bandwidth"
  - "Frontend-driven data requirements"
  - "Rapid prototyping and iteration"
  - "Aggregating multiple data sources"
  - "When you need flexible queries"

// GraphQL with Apollo Server
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';

const typeDefs = `
  type User {
    id: ID!
    name: String!
    email: String!
    posts: [Post!]!
  }
  
  type Post {
    id: ID!
    title: String!
    author: User!
  }
  
  type Query {
    users: [User!]!
    user(id: ID!): User
  }
  
  type Mutation {
    createUser(name: String!, email: String!): User!
  }
`;

const resolvers = {
  Query: {
    users: () => db.user.findMany(),
    user: (_, { id }) => db.user.findUnique({ where: { id } }),
  },
  User: {
    posts: (parent) => db.post.findMany({
      where: { authorId: parent.id }
    }),
  },
  Mutation: {
    createUser: (_, args) => db.user.create({ data: args }),
  },
};

const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await startStandaloneServer(server);

# Get user with posts (exactly what you need)
query GetUserWithPosts {
  user(id: "123") {
    name
    email
    posts {
      title
    }
  }
}

# Multiple resources in one request
query DashboardData {
  currentUser {
    name
    notifications {
      message
    }
  }
  trendingPosts {
    title
    likes
  }
}

trpc_scenarios:
  - "TypeScript/Next.js projects"
  - "When type safety is critical"
  - "Internal APIs (not public)"
  - "Simple data requirements"
  - "When you want zero boilerplate"
  - "Full-stack TypeScript teams"

// Server: Define router
// src/server/api/routers/user.ts
import { z } from 'zod';
import { createTRPCRouter, publicProcedure } from '../trpc';

export const userRouter = createTRPCRouter({
  getById: publicProcedure
    .input(z.object({ id: z.string() }))
    .query(({ input, ctx }) => {
      return ctx.db.user.findUnique({
        where: { id: input.id }
      });
    }),

  getAll: publicProcedure.query(({ ctx }) => {
    return ctx.db.user.findMany();
  }),

  create: publicProcedure
    .input(z.object({
      name: z.string().min(1),
      email: z.string().email()
    }))
    .mutation(({ input, ctx }) => {
      return ctx.db.user.create({
        data: input
      });
    }),
});

// Client: Use with full type safety
// src/pages/users.tsx
import { api } from '@/utils/api';

export default function UsersPage() {
  // Fully typed - IDE knows exact return type!
  const { data: users, isLoading } = api.user.getAll.useQuery();
  
  const createUser = api.user.create.useMutation();
  
  if (isLoading) return <div>Loading...</div>;
  
  return (
    <div>
      {users?.map(user => (
        <div key={user.id}>{user.name}</div>
      ))}
    </div>
  );
}

# Performance comparison
rest:
  pros:
    - "HTTP caching works out of the box"
    - "Simple to cache at CDN level"
    - "Stateless = easy to scale"
  cons:
    - "N+1 queries common"
    - "Over-fetching common"
    
graphql:
  pros:
    - "Request exactly what's needed"
    - "Dataloader solves N+1"
  cons:
    - "Complex queries can be slow"
    - "Caching requires more setup"
    
trpc:
  pros:
    - "No over-fetching by design"
    - "Uses React Query caching"
  cons:
    - "Not cached at HTTP level"
    - "Best with internal APIs"