tRPC, REST and OpenAPI

"Should we use tRPC or REST?" is a common design question, and the honest answer is "it depends on who calls the API". This lesson shows both styles in small programs you can run, then covers the parts that decide whether an API stays healthy for years: contract tests, versioning, error shapes and idempotency keys.

This lesson does not repeat the basics. For resources, status codes, pagination and URL versioning, see Backend, Lesson 02. For GraphQL and Hasura (the third option), see Full-Stack Q&A, Lesson 09. For validating input at the edge, see Backend, Lesson 03. For contract tests in a test plan, see Backend, Lesson 11.

Words used in this lesson

• RPC (remote procedure call) means calling a function that runs on another computer. The call looks like a function call; HTTP is hidden underneath. tRPC is "TypeScript RPC".
• A procedure is one function exposed by a tRPC server. A query reads data. A mutation changes data. A router is a group of procedures.
• End-to-end type safety means the compiler checks the data shape from the database row to the screen, so a rename on the server breaks the client build instead of production.
• Type inference means TypeScript works out a type from the code, without you writing it. tRPC uses it to build client types straight from the server code.
• A schema is a description of allowed data. Zod is a TypeScript library that checks data at run time and also gives you the TypeScript type.
• OpenAPI is a standard file format (JSON or YAML) that describes an HTTP API: paths, methods, inputs, outputs and errors. It is the successor of "Swagger". Tools can read it to make docs, clients and tests.
• JSON Schema is a standard way to describe the shape of JSON. OpenAPI 3.1 uses JSON Schema (draft 2020-12) for its data models.
• Code-first means you write the code (and schemas) and generate the OpenAPI file. Design-first (or contract-first) means you write the OpenAPI file first and build the code from it.
• A contract is the agreement between caller and API: what you can send and what you get back.
• A breaking change is a change that makes a correct old client fail. A backward-compatible change keeps old clients working.
• RFC 9457 "problem details" is a standard JSON shape for HTTP errors, with the media type application/problem+json.
• An idempotency key is a unique value the client sends with a request, so the server can recognise a retry of the same request and not do the work twice.

Part 1. tRPC: types without a schema file

How it works

You write procedures on the server. You export only the type of the router. The client imports that type, and TypeScript works out every input and output. There is no code generation step. The tRPC docs describe it as "fully typesafe APIs without schemas or code generation". The docs also say that, underneath, it is plain HTTP, and you should think "functions", not "verbs and URLs".

// router.ts  (server)import { initTRPC, TRPCError } from '@trpc/server';import { z } from 'zod';const t = initTRPC.create();const users = new Map([[1, { id: 1, name: 'Asha', email: 'asha@example.com' }]]);export const appRouter = t.router({  userById: t.procedure    .input(z.object({ id: z.number().int().positive() }))    .query(({ input }) => {      const user = users.get(input.id);      if (!user) throw new TRPCError({ code: 'NOT_FOUND', message: `user ${input.id} not found` });      return user;    }),  createUser: t.procedure    .input(z.object({ name: z.string().min(1), email: z.email() }))    .mutation(({ input }) => {      const user = { id: users.size + 1, ...input };      users.set(user.id, user);      return user;    }),});export type AppRouter = typeof appRouter;   // only the TYPE crosses to the client

// main.ts  (client, run in the same file as the server for the demo)import { createHTTPServer } from '@trpc/server/adapters/standalone';import { createTRPCClient, httpBatchLink, TRPCClientError } from '@trpc/client';const server = createHTTPServer({ router: appRouter }).listen(0);const client = createTRPCClient<AppRouter>({ links: [httpBatchLink({ url })] });const u = await client.userById.query({ id: 1 });          // u is { id: number; name: string; email: string }const c = await client.createUser.mutate({ name: 'Ben', email: 'ben@example.com' });

What it printed: typed result: { id: 1, name: 'Asha', email: 'asha@example.com' }, then created: { id: 2, name: 'Ben', ... }. The missing user (id: 99) threw a TRPCClientError with data.code = 'NOT_FOUND' and data.httpStatus = 404.

The compiler catches the mistakes

I wrote a file with three deliberate mistakes and ran tsc:

await client.userById.query({ id: '1' });       // wrong input typeconsole.log(a.nmae);                            // typo in an output fieldawait client.userByEmail.query({ email: 'a@b.c' }); // procedure does not exist

t1/bad.ts(4,41): error TS2322: Type 'string' is not assignable to type 'number'.t1/bad.ts(5,15): error TS2339: Property 'nmae' does not exist on type '{ id: number; name: string; email: string; }'.t1/bad.ts(6,14): error TS2339: Property 'userByEmail' does not exist on type 'TRPCClient<...>'.

This is the whole selling point. If you rename email to emailAddress on the server, every client call that uses it fails to compile.

What is on the wire

I called the server with plain fetch to see the HTTP (it is ordinary HTTP, but it is tRPC's own format, not a REST design):

Two details I checked. In development the error data also had a stack field; with NODE_ENV=production it was gone. And httpBatchLink can combine several calls made at the same time into one HTTP request (from the docs; I did not measure it).

The error codes (NOT_FOUND, BAD_REQUEST, UNAUTHORIZED and so on) map to HTTP statuses, and getHTTPStatusCodeFromError gives you the number. The error body is tRPC's own format, so it is not RFC 9457. Anyone who calls it without the tRPC client must learn that format.

Where tRPC fits and where it hurts

Other things to know:

• Coupling is the price. The client imports the server's type, so they must live in a shared TypeScript build. That is easy in a monorepo and awkward across repos.
• There is no built-in public contract. The "contract" is your TypeScript code. There is nothing a Python team can read. If you later need one, you can add a generated OpenAPI layer (Part 2).
• Version handling is manual. tRPC has no /v1 idea. You keep it safe by making additive changes only, or by deploying client and server together.
• Validation is still your job. The types vanish at run time. The .input(z.object(...)) line is what protects you from bad data, and the TypeScript types come from it. Server-side checks of who may call the procedure (authorization) go in middleware or in the procedure, not in the type.
• Subscriptions (live updates) are supported. The docs recommend Server-Sent Events over WebSockets when you are unsure, because it is easier to set up.

Part 2. REST with an OpenAPI document

What the document is

An OpenAPI document lists every path and method, with its parameters, request body, and each possible response. Here is a small one for two endpoints. I did not write it by hand: I built it from the same Zod schemas the server uses (next section).

{  "openapi": "3.1.0",  "info": { "title": "Users API", "version": "1.0.0" },  "paths": {    "/users/{id}": { "get": { "operationId": "getUser",      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }],      "responses": {        "200": { "description": "The user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } },        "404": { "description": "Problem Details (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } },    "/users": { "post": { "operationId": "createUser",      "parameters": [{ "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }],      "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUser" } } } },      "responses": { "201": { "...": "User" }, "422": { "...": "Problem" } } } }  },  "components": { "schemas": { "User": {}, "CreateUser": {}, "Problem": {} } }}

OpenAPI 3.1 treats its schema objects as JSON Schema draft 2020-12 (the 3.1.1 spec says so). The spec repository's main branch now also holds a 3.2.0 text, but I did not test any tool against 3.2, so I used 3.1.

Zod to OpenAPI: the main approaches

You do not want two sources of truth (the Zod schema and a hand-written file that drifts). These are the common routes:

My Zod 4 route, in short:

const js = (s) => z.toJSONSchema(s, { target: 'draft-2020-12', io: 'input' });const doc = { openapi: '3.1.0', info: {...}, paths: {...},  components: { schemas: { User: js(User), CreateUser: js(CreateUser), Problem: js(Problem) } } };

Things I saw in the output: z.int() became "type": "integer" with minimum and maximum set to the safe-integer limits (-9007199254740991 and 9007199254740991). z.email() became "format": "email" plus a long pattern. Optional fields were left out of required. Remove the $schema key that toJSONSchema adds if you embed the result.

With trpc-to-openapi, I added OpenApiMeta to initTRPC, put .meta({ openapi: { method: 'GET', path: '/users/{id}', tags: ['users'] } }) on a procedure, and the generator returned a 3.1.0 document with the path /users/{id} and the id as a path parameter. Note that REST needs real path parameters as strings, so I used z.coerce.number() for id. One surprise: the project README says protect defaults to false, but in version 3.3.0 the code has protect = true as the default, and my generated operation had a security entry. Set protect explicitly.

Generate a typed client from the document

npx openapi-typescript openapi.json -o schema.d.ts

The tool printed openapi.json -> schema.d.ts [91.1ms] and wrote types such as:

export interface paths { "/users/{id}": { get: operations["getUser"]; ... }; "/users": { post: operations["createUser"]; ... } }export interface components { schemas: {  User: { id: number; name: string; /** Format: email */ email: string };  Problem: { type: string; title: string; status: number; detail?: string; instance?: string };} }

openapi-fetch reads those types and gives you a small client (no code is generated, it is only types plus a thin fetch wrapper):

import createClient from 'openapi-fetch';import type { paths } from './schema.d.ts';const api = createClient<paths>({ baseUrl });const ok = await api.GET('/users/{id}', { params: { path: { id: 1 } } });const miss = await api.GET('/users/{id}', { params: { path: { id: 42 } } });console.log(miss.response.status, miss.error);   // error is typed as Problem

Real output: GET 1 -> 200 { id: 1, name: 'Asha', ... } and for id 42 404 with { type: 'https://api.example.com/problems/user-not-found', title: 'User not found', status: 404, detail: 'No user with id 42.', instance: '/users/42' }. And the compiler errors for wrong use:

t2/bad.ts(4,15): error TS2345: Argument of type '"/user/{id}"' is not assignable to parameter of type '"/users/{id}"'.t2/bad.ts(5,50): error TS2322: Type 'string' is not assignable to type 'number'.t2/bad.ts(7,13): error TS18048: 'r.data' is possibly 'undefined'.

The third error is the most useful: data is only defined on success, so the client makes you handle the failure case.

Part 3. Contract testing

A contract test checks that what the server really returns matches the contract. Two directions are common:

• Provider check (schema based). Call the real API and check each response against the schemas in the OpenAPI document. Tools such as Schemathesis can generate the calls from the document (not tested by me).
• Consumer-driven contracts. Each client writes down what it needs (its calls and the parts of the reply it uses). The server runs those files in its build. Pact is the well known tool (not tested by me; @pact-foundation/pact is on npm). This helps when you have several clients and want to know which one a change would break.

I wrote the first kind with Ajv, in about twenty lines. It loads the document, runs the real server, and validates the body:

const ajv = new Ajv2020({ strict: false });  addFormats.default(ajv);ajv.addSchema({ $id: 'doc', components: doc.components });const validate = ajv.getSchema('doc#/components/schemas/User')!;validate(body) ? 'ok' : ajv.errorsText(validate.errors);

GET /users/{id} id=1 -> 200: okGET /users/{id} id=42 -> 404: okdrifted body: data must have required property 'name'

The "drifted body" is a response where someone renamed name to fullName and did not update the document. The check fails with a clear message. Put this in CI, so a mismatch fails the pull request, not a customer.

Also add a breaking-change diff between the old and new document in CI. Tools that compare two OpenAPI files exist (for example oasdiff; I did not run one), and the rules they apply are the ones in the next section.

Part 4. Versioning and breaking changes

Do not repeat the URL-versus-header debate here (it is in Backend, Lesson 02). What matters more is which changes are breaking. These rules are common practice, not a standard:

Practical habits:

• Be a tolerant reader. Tell clients to ignore unknown response fields. Generated clients that are too strict (they reject unknown fields) turn safe changes into breaks.
• Expand, then contract. Add the new field, move clients over, measure usage, then remove the old field. The same idea is used for database migrations.
• Announce removal with headers. The Deprecation header (from an IETF HTTP working-group document I read; its example value is a date as @1688169599, a Unix time) says "this is deprecated since then". The Sunset header (RFC 8594) says when it will stop working. The Sunset date must not be earlier than the Deprecation date. Also put it in the OpenAPI document with deprecated: true.
• Measure before you remove. Log which clients (by API key or User-Agent) still call the old field.
• A new major version is the last resort, because you must run both. It is the right tool when the resource model itself changes.
• With tRPC, the safe rule is the same additive rule, plus: because the client and server share a build, a bad change fails at compile time if both are in the same repo. Old deployed mobile or cached browser bundles can still call the old shape, so keep old procedures for a while.

Part 5. Error shapes: RFC 9457 problem details

Backend, Lesson 02 says "use one error format". RFC 9457 (it obsoletes RFC 7807) is the standard one. I read the text in its source repository. The key facts:

• Media type: application/problem+json (and an XML twin, application/problem+xml).
• Members: type (a URI that names the kind of problem; if missing it means about:blank, "no extra meaning beyond the HTTP status"), title (short, should not change between occurrences), status, detail (this occurrence, for people), instance (a URI for this occurrence).
• You can add extension members, such as errors for field-by-field validation messages or a traceId.
• Clients must use type as the identifier. They should not parse detail; put machine-readable facts in extension members.
• Clients should not automatically fetch the type URL, but if it is a real URL it should show human documentation.
• The response may be sent as application/problem+json even if the client did not list it in Accept.

The server I ran sends this for a missing user (status 404, header Content-Type: application/problem+json):

{ "type": "https://api.example.com/problems/user-not-found",  "title": "User not found", "status": 404,  "detail": "No user with id 42.", "instance": "/users/42" }

function problem(res, status, title, detail, instance) {  res.writeHead(status, { 'content-type': 'application/problem+json' });  res.end(JSON.stringify({ type: `https://api.example.com/problems/${slug(title)}`, title, status, detail, instance }));}

For a validation error with several fields I used 422 and put the issues in detail as text. A better design adds an extension member, for example "errors": [{ "pointer": "/email", "message": "Invalid email address" }], so no one has to parse text.

How this compares: a tRPC server returns its own JSON-RPC-like shape (shown above). If you expose the same logic as REST, make the REST layer return problem details, and have a clear mapping from your internal error codes to type URIs.

Part 6. Idempotency keys

A network can fail after the server did the work. The client does not know, so it retries. For GET, PUT and DELETE a retry is safe by design (see Browser, Lesson 06). For POST (create an order, send money) a retry may do it twice. The fix is an Idempotency-Key header: a random value (a UUID is recommended) chosen by the client, the same on every retry of one action.

The IETF draft for this header (I read the working-group source; it is a draft, so check its status before you rely on its exact wording) says:

• The server defines and documents the key rules, including how long keys are kept.
• Missing key on an endpoint that needs one: reply 400.
• Same key but a different request body: reply 422.
• Same key while the first request is still running: reply 409.
• Otherwise a repeat returns the stored result of the first request.

My demo server follows that. The client sent the same request twice with key k-123:

POST #1 201 { id: 2, name: 'Ben', ... }POST #2 (retry) 201 { id: 2, name: 'Ben', ... }   replayed = truesame key, new body -> 422 Idempotency key reused

Only one user was created. The core of the code:

const prev = seen.get(key);if (prev) {  if (prev.bodyJson !== bodyJson) return problem(res, 422, 'Idempotency key reused', ...);  return json(res, prev.status, prev.out, { 'idempotent-replayed': 'true' });}// ...do the work, then:seen.set(key, { bodyJson, status: 201, out: user });

Where this shows up: payment APIs and webhooks. See Full-Stack Q&A, Lesson 19 (queues, retries, webhooks) and Lesson 23 (payments).

Part 7. How to choose

Ask these questions in order:

1. Who are the callers? Only your own TypeScript web app: tRPC (or plain functions and Server Actions) is great. Partners, other languages, mobile apps, or the public: REST with OpenAPI.
2. Can you deploy client and server together? Yes: tRPC's tight coupling is fine. No (mobile apps, long-lived integrations): you need an explicit versioned contract.
3. Do you need documentation and SDKs for outsiders? If yes, an OpenAPI document is the product, not an extra.
4. Do clients need to choose their own fields across many related types? Consider GraphQL or Hasura (Lesson 09, Backend, Lesson 09).
5. Do you need URL-based HTTP caching, webhooks or simple curl testing? REST fits better.

A common, sensible mix: tRPC (or typed server functions) for your own web app, and a small REST + OpenAPI surface for the parts partners use. trpc-to-openapi can expose chosen procedures that way, but only add it if you will keep that public surface stable, since it becomes a promise you must keep.

Common mistakes

• Choosing tRPC for an API that outside teams will call, then writing docs by hand later.
• Treating generated client types as proof. They only match the document, not the running server, until a contract test checks it.
• Hand-writing the OpenAPI file next to the code, so the two drift.
• Calling a change "safe" because the compiler passes, when old mobile clients are still in use.
• Adding a required request field, making a field nullable or tightening validation, and calling it a minor version.
• Returning a custom error shape from every endpoint, or parsing detail text in the client.
• Putting stack traces or internal ids in an error body.
• Idempotency keys stored after the work is done (race), kept forever, or shared across users.
• Retrying POST automatically in the client without an idempotency key.

Interview questions

Key takeaways

• tRPC: types flow from the server router to the client with no schema file. It is excellent when one TypeScript team owns both sides, and weak as a public API.
• OpenAPI: a written, language-neutral contract. Generate it from your Zod schemas (or write it first) so there is one source of truth, then generate client types from it.
• Generated types only match the document. Add a contract test in CI so the running server cannot drift unnoticed.
• Adding optional things is safe. Removing, renaming, retyping, making required, making nullable and tightening validation are breaking. Expand, measure, then contract, and announce with Deprecation and Sunset.
• Use RFC 9457 problem details for REST errors. Use type as the identifier, add extension members for data, and keep internals out of detail.
• POST retries need idempotency keys. Reserve the key atomically, scope it per user, and expire it.
• Choose by caller: your own TypeScript app, tRPC; outsiders, REST + OpenAPI; flexible data shapes, GraphQL. Mixing them is normal.

What's next

Next, Security in depth for full-stack developers covers the attacks that hit APIs like these: SSRF, injection, unsafe input and weak password storage. For auth on these endpoints, see Lesson 22.