REST, GraphQL, gRPC, tRPC and webhooks: choosing an API style

HOW IT FITS TOGETHER

KEY TERMS

Contracts

OpenAPI describes HTTP resources, parameters, status codes and media types (3.2.0, September 2025, uses JSON Schema 2020-12). GraphQL SDL describes a typed graph that the server enforces on every request. Protobuf describes messages and services and generates clients in many languages. tRPC has no contract file: the router's TypeScript type is the contract, which only works while both sides compile together. Generate from or validate against the contract in CI, or it will drift.

Error models

REST should use real status codes plus RFC 9457 problem details (application/problem+json with type, title, status, detail, instance and extension members); it obsoletes RFC 7807. GraphQL returns errors[] alongside partial data, usually with 200, so monitoring must read the body; model expected business failures as union result types. gRPC and Connect use a fixed set of status codes (NOT_FOUND, INVALID_ARGUMENT, UNAVAILABLE) plus typed error details. tRPC throws TRPCError with codes mapped to HTTP statuses.

Caching

REST GETs get browser and CDN caching for free (see the HTTP caching explainer). GraphQL over POST bypasses HTTP caches; GET with persisted queries (the client sends a hash) makes it cacheable and also allowlists operations. gRPC is POST over HTTP/2; Connect can send methods marked idempotency_level = NO_SIDE_EFFECTS as GET so CDNs can cache them. Most GraphQL and tRPC caching ends up client-side (normalised caches, TanStack Query).

Versioning

Additive change is the default everywhere: new optional fields, new endpoints, never repurposed meanings. REST breaks go to /v2 or a dated version header. GraphQL marks fields @deprecated and watches field usage before removal. Protobuf field numbers identify fields on the wire, so removed fields must be reserved, never reused. Webhook payloads need versioned event types because you cannot redeploy the receivers.

Pagination

Offset pagination (?page=40) is simple but slow on deep pages and skips or repeats rows when data changes. Cursor (keyset) pagination encodes the last row's sort key (created_at, id) in an opaque cursor and uses an index range scan. GraphQL's Relay connection spec (edges, pageInfo.endCursor, hasNextPage) is the same idea.

N+1 in GraphQL

Resolvers run per field per object, so a list of 20 posts each resolving author makes 20 queries. DataLoader batches all load(key) calls made in the same tick into one batch function call and memoises keys for the request. Create one loader per request: its cache is request-scoped memoisation, and sharing it across users leaks data past authorization checks.

gRPC in browsers

Browsers cannot speak native gRPC (no access to HTTP/2 framing or trailers), so gRPC-Web uses its own wire format through a proxy such as Envoy, with unary and server-streaming calls only. Connect servers speak gRPC, gRPC-Web and the Connect protocol (plain HTTP/1.1 or HTTP/2 with JSON or binary) from the same handlers, so browsers can call them without a proxy.

IN YOUR STACK

openapi: 3.2.0
info: { title: Orders API, version: "1.4.0" }
paths:
  /v1/orders/{id}:
    get:
      operationId: getOrder
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200":
          description: The order
          headers: { ETag: { schema: { type: string } } }
          content: { application/json: { schema: { $ref: "#/components/schemas/Order" } } }
        "404":
          description: No order with this id for the caller
          content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } }
components:
  schemas:
    Problem:   # RFC 9457
      type: object
      properties:
        type: { type: string, format: uri-reference, default: "about:blank" }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
        instance: { type: string, format: uri-reference }

import DataLoader from "dataloader";

export const typeDefs = /* GraphQL */ `
  type User { id: ID!  name: String! }
  type Post { id: ID!  title: String!  author: User }
  type Query { posts(first: Int = 20, after: String): [Post!]! }
`;

type Ctx = { viewer: Viewer; users: DataLoader<string, User | null> };

// Called once per request by your server (Yoga, Apollo, Mercurius...).
export function createContext(viewer: Viewer): Ctx {
  const users = new DataLoader<string, User | null>(async (ids) => {
    const rows = await db.user.findMany({ where: { id: { in: [...ids] } } });
    const byId = new Map(rows.map((u) => [u.id, u]));
    return ids.map((id) => byId.get(id) ?? null); // same length and order as ids
  }, { maxBatchSize: 500 });
  return { viewer, users };
}

export const resolvers = {
  Query: { posts: (_: unknown, args: { first: number; after?: string }, ctx: Ctx) =>
    listPostsVisibleTo(ctx.viewer, Math.min(args.first, 100), args.after) },
  Post: { author: (post: Post, _: unknown, ctx: Ctx) => ctx.users.load(post.authorId) },
};

// proto/orders/v1/orders.proto
syntax = "proto3";
package orders.v1;

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order) {
    option idempotency_level = NO_SIDE_EFFECTS; // Connect clients may use GET
  }
}
message GetOrderRequest { string id = 1; }
message Order {
  reserved 3;                 // removed field: the number is never reused
  string id = 1;
  int64 total_cents = 2;
}

// src/routes.ts (code generated with buf + protoc-gen-es)
import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
import { OrderService } from "./gen/orders/v1/orders_pb";

export default (router: ConnectRouter) =>
  router.service(OrderService, {
    async getOrder(req, ctx) {
      const order = await findOrder(req.id, ctx.requestHeader.get("authorization"));
      if (!order) throw new ConnectError(`order ${req.id} not found`, Code.NotFound);
      return { id: order.id, totalCents: BigInt(order.totalCents) };
    },
  });

import { initTRPC, TRPCError } from "@trpc/server";
import { z } from "zod";

type Context = { user: { id: string } | null };
const t = initTRPC.context<Context>().create();

const authed = t.procedure.use(({ ctx, next }) => {
  if (!ctx.user) throw new TRPCError({ code: "UNAUTHORIZED" });
  return next({ ctx: { user: ctx.user } });
});

export const appRouter = t.router({
  order: t.router({
    byId: authed.input(z.object({ id: z.uuid() })).query(async ({ ctx, input }) => {
      const order = await findOrder(input.id, ctx.user.id);
      if (!order) throw new TRPCError({ code: "NOT_FOUND", message: "Order not found" });
      return order;
    }),
    cancel: authed
      .input(z.object({ id: z.uuid(), reason: z.string().max(200) }))
      .mutation(({ ctx, input }) => cancelOrder(input.id, ctx.user.id, input.reason)),
  }),
});

// Only the type crosses to the client: createTRPCClient<AppRouter>({ links: [httpBatchLink({ url: "/trpc" })] })
export type AppRouter = typeof appRouter;

// GET /v1/orders?limit=50&cursor=eyJ0IjoiMjAyNi0xMS0wNl...
app.get("/v1/orders", async (req, res) => {
  const limit = clampInt(req.query.limit, { min: 1, max: 100, fallback: 50 });
  const after = decodeCursor(req.query.cursor); // { createdAt, id } | null | "invalid"
  if (after === "invalid") {
    return res.status(400).type("application/problem+json").json({
      type: "https://api.example.com/problems/invalid-cursor",
      title: "Invalid cursor", status: 400, detail: "Restart from the first page.",
    });
  }
  const { rows } = await pool.query(
    `SELECT id, total_cents, created_at FROM orders
     WHERE tenant_id = $1 AND ($2::timestamptz IS NULL OR (created_at, id) < ($2, $3))
     ORDER BY created_at DESC, id DESC LIMIT $4`,
    [req.tenantId, after?.createdAt ?? null, after?.id ?? null, limit + 1],
  );
  const page = rows.slice(0, limit);
  const next = rows.length > limit ? encodeCursor(page.at(-1)!) : null;
  if (next) res.links({ next: `/v1/orders?limit=${limit}&cursor=${next}` });
  res.json({ data: page, next_cursor: next, has_more: next !== null });
});
// -> { "data": [...50 orders], "next_cursor": "eyJ0Ijoi...", "has_more": true }

WHEN TO REACH FOR WHAT

WHERE IT BITES

• Choosing GraphQL for one web client and then rebuilding HTTP caching, rate limiting by cost and error monitoring that REST would have given for free.
• Running a public GraphQL endpoint without depth, breadth or cost limits and without persisted queries, which lets a single crafted query exhaust the database.
• Returning 200 with { "error": ... } bodies from REST endpoints. Caches, retries, monitoring and client libraries all key on the status code; use 4xx/5xx with application/problem+json.
• Reusing or renumbering protobuf fields. Old binaries decode the new data into the wrong field without any error.
• Treating tRPC's shared types as a versioned contract. They only guarantee compatibility for code compiled together, not for mobile apps or tabs open since the last deploy.
• Offset pagination on large, changing tables: deep pages get slower linearly and concurrent inserts make clients skip or duplicate items.

WHEN IT BREAKS IN PRODUCTION

• The frontend breaks when the API response changes
• A backend deploy breaks old app versions
• Paging through a list skips or repeats items
• An endpoint gets slower as results grow
• Webhooks arrive twice, late, or out of order
• A third-party API starts returning 429
• One request waits on a chain of services and times out

SOURCES

• RFC 9457: Problem Details for HTTP APIs (opens in new tab)Checked 2026-11-06
• OpenAPI Specification v3.2.0 (opens in new tab)Checked 2026-11-06
• GraphQL: Performance (opens in new tab)Checked 2026-11-06
• DataLoader README (opens in new tab)Checked 2026-11-06
• Connect: Get requests and caching (opens in new tab)Checked 2026-11-06
• gRPC-Web (opens in new tab)Checked 2026-11-06