tRPC vs REST vs GraphQL: Type-Safe APIs in Next.js 2026

// server/routers/user.ts
import { router, protectedProcedure } from '../trpc';
import { z } from 'zod';

export const userRouter = router({
  getProfile: protectedProcedure
    .query(async ({ ctx }) => {
      return ctx.db.user.findUnique({
        where: { id: ctx.session.user.id },
      });
    }),

  updateProfile: protectedProcedure
    .input(z.object({
      name: z.string().min(1).max(100),
      bio: z.string().max(500).optional(),
    }))
    .mutation(async ({ input, ctx }) => {
      return ctx.db.user.update({
        where: { id: ctx.session.user.id },
        data: input,
      });
    }),

  getUsageStats: protectedProcedure
    .input(z.object({ days: z.number().min(1).max(365).default(30) }))
    .query(async ({ input, ctx }) => {
      const since = new Date();
      since.setDate(since.getDate() - input.days);
      return ctx.db.event.count({
        where: { userId: ctx.session.user.id, createdAt: { gte: since } },
      });
    }),
});

// server/root.ts — merge all routers
import { router } from './trpc';
import { userRouter } from './routers/user';
import { billingRouter } from './routers/billing';
import { teamRouter } from './routers/team';

export const appRouter = router({
  user: userRouter,
  billing: billingRouter,
  team: teamRouter,
});

export type AppRouter = typeof appRouter;

// app/api/trpc/[trpc]/route.ts — Next.js App Router handler
import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import { appRouter } from '@/server/root';
import { createContext } from '@/server/context';

const handler = (req: Request) =>
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req,
    router: appRouter,
    createContext,
  });

export { handler as GET, handler as POST };

// Client usage — fully typed, no boilerplate:
import { api } from '@/lib/trpc/client';

export function ProfilePage() {
  // Return type is inferred from server definition:
  const { data: profile } = api.user.getProfile.useQuery();

  const updateProfile = api.user.updateProfile.useMutation({
    onSuccess: () => toast.success('Profile updated!'),
  });

  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      updateProfile.mutate({ name: e.currentTarget.name.value });
    }}>
      <input name="name" defaultValue={profile?.name ?? ''} />
      <button type="submit" disabled={updateProfile.isPending}>
        {updateProfile.isPending ? 'Saving...' : 'Save'}
      </button>
    </form>
  );
}

// app/api/users/[id]/route.ts
import { auth } from '@/auth';
import { db } from '@/lib/db';
import { z } from 'zod';
import { NextResponse } from 'next/server';

export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const session = await auth();
  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, name: true, email: true, createdAt: true },
  });

  if (!user) {
    return NextResponse.json({ error: 'Not found' }, { status: 404 });
  }

  return NextResponse.json(user);
}

const updateUserSchema = z.object({
  name: z.string().min(1).max(100).optional(),
  bio: z.string().max(500).optional(),
});

export async function PATCH(
  request: Request,
  { params }: { params: { id: string } }
) {
  const session = await auth();
  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  if (session.user.id !== params.id) {
    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
  }

  const body = await request.json();
  const parsed = updateUserSchema.safeParse(body);
  if (!parsed.success) {
    return NextResponse.json({ error: parsed.error.flatten() }, { status: 422 });
  }

  const user = await db.user.update({
    where: { id: params.id },
    data: parsed.data,
  });

  return NextResponse.json(user);
}

// types/api.ts — manually maintained types
export interface User {
  id: string;
  name: string;
  email: string;
  createdAt: string;
}

export interface UpdateUserInput {
  name?: string;
  bio?: string;
}

// Client — types are not inferred, must be maintained separately:
async function updateUser(id: string, data: UpdateUserInput): Promise<User> {
  const res = await fetch(`/api/users/${id}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });

  if (!res.ok) throw new Error('Update failed');
  return res.json() as Promise<User>;
}

# openapi.yaml
openapi: 3.0.0
paths:
  /api/users/{id}:
    get:
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

npx openapi-typescript openapi.yaml -o types/api.d.ts

// npm install @apollo/server graphql
// app/api/graphql/route.ts

import { ApolloServer } from '@apollo/server';
import { startServerAndCreateNextHandler } from '@as-integrations/next';
import { gql } from 'graphql-tag';
import { db } from '@/lib/db';

const typeDefs = gql`
  type User {
    id: ID!
    name: String!
    email: String!
    projects: [Project!]!
    usageStats(days: Int): UsageStats!
  }

  type Project {
    id: ID!
    name: String!
    memberCount: Int!
  }

  type UsageStats {
    messageCount: Int!
    tokensUsed: Int!
    estimatedCost: Float!
  }

  type Query {
    me: User
    user(id: ID!): User
  }

  type Mutation {
    updateProfile(name: String, bio: String): User!
  }
`;

const resolvers = {
  Query: {
    me: async (_: unknown, __: unknown, ctx: Context) => {
      if (!ctx.userId) throw new Error('Unauthorized');
      return ctx.db.user.findUnique({ where: { id: ctx.userId } });
    },
    user: async (_: unknown, { id }: { id: string }, ctx: Context) => {
      return ctx.db.user.findUnique({ where: { id } });
    },
  },

  User: {
    // Field resolvers — only fetched when client requests them:
    projects: async (user: { id: string }, _: unknown, ctx: Context) => {
      return ctx.db.project.findMany({ where: { userId: user.id } });
    },
    usageStats: async (
      user: { id: string },
      { days = 30 }: { days?: number },
      ctx: Context
    ) => {
      const since = new Date();
      since.setDate(since.getDate() - days);
      const result = await ctx.db.aiUsage.aggregate({
        where: { userId: user.id, createdAt: { gte: since } },
        _count: { id: true },
        _sum: { totalTokens: true, estimatedCostUsd: true },
      });
      return {
        messageCount: result._count.id,
        tokensUsed: result._sum.totalTokens ?? 0,
        estimatedCost: Number(result._sum.estimatedCostUsd ?? 0),
      };
    },
  },

  Mutation: {
    updateProfile: async (
      _: unknown,
      input: { name?: string; bio?: string },
      ctx: Context
    ) => {
      if (!ctx.userId) throw new Error('Unauthorized');
      return ctx.db.user.update({
        where: { id: ctx.userId },
        data: input,
      });
    },
  },
};

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

export const GET = startServerAndCreateNextHandler(server, {
  context: async (req) => ({ db, userId: getUserIdFromRequest(req) }),
});
export const POST = GET;

// Client with @apollo/client:
import { gql, useQuery } from '@apollo/client';

const GET_ME = gql`
  query GetMe {
    me {
      id
      name
      # Client chooses exactly what fields to fetch:
      usageStats(days: 30) {
        messageCount
        tokensUsed
      }
      # Projects only fetched if included in query:
      projects {
        id
        name
      }
    }
  }
`;

export function Dashboard() {
  const { data, loading } = useQuery(GET_ME);
  if (loading) return <Skeleton />;

  return (
    <div>
      <h1>Welcome, {data.me.name}</h1>
      <p>{data.me.usageStats.messageCount} messages this month</p>
    </div>
  );
}

// Server Action — no API layer at all:
'use server';
export async function updateProfile(formData: FormData) {
  const session = await auth();
  // Runs on server, no HTTP round-trip, no API to define
  await db.user.update({ where: { id: session.user.id }, data: {...} });
  revalidatePath('/dashboard');
}

Choose tRPC if:
  → Full-stack TypeScript Next.js app
  → Internal API (no external consumers)
  → Team wants zero boilerplate
  → Using React Query already
  → T3 Stack or similar monorepo

Choose REST if:
  → Public API that others will consume
  → Mobile app clients (iOS, Android)
  → Non-TypeScript consumers
  → Simple CRUD without complex data needs
  → Team unfamiliar with tRPC

Choose GraphQL if:
  → Multiple client types with different data requirements
  → Complex nested data (social graph, CMS, reporting)
  → Large team where schema acts as contract
  → You're already invested in GraphQL tooling
  → Mobile app that benefits from precise field selection