Designing Typed API Contracts

A typed API contract names request inputs, response fields, and error cases. The same contract may be used by client and server code, but a TypeScript interface disappears at runtime. Validate incoming HTTP data before treating it as the contract, and version changes that would break clients.

The typed request contains only the title. The function normalizes the text and creates a response with an ID and done field. An HTTP endpoint would also need validation and status codes.

Sharing TypeScript types between client and server is not runtime validation and cannot protect against an outdated or malicious client.

This source was compiled using TypeScript 5.8.3 with strict checking, then executed with Node.js 22.16.0. Its stdout below is the actual captured output. The core logic is runnable without a framework or a remote API; integration-specific examples appear in a separate lab when needed.

TypeScript source

type CreateTask = { title: string };
type TaskResponse = { id: number; title: string; done: boolean };
function createTask(request: CreateTask, nextId: number): TaskResponse {
  return { id: nextId, title: request.title.trim(), done: false };
}
console.log(JSON.stringify(createTask({ title: "  Study  " }, 12)));

Verified output

{"id":12,"title":"Study","done":false}

Compile: npx tsc --strict --target es2022 --module commonjs designing-typed-api-contracts.ts; run: node designing-typed-api-contracts.js. For examples importing node: modules, install @types/node as a development dependency; for browser or React projects use the separate lab setup.

The typed request contains only the title. The function normalizes the text and creates a response with an ID and done field. An HTTP endpoint would also need validation and status codes.

Before editing the code, predict what the output will be for one changed input. Run it and compare your prediction with the actual result.

Sharing TypeScript types between client and server is not runtime validation and cannot protect against an outdated or malicious client.

Determine whether the issue belongs to the type system, a trust boundary, or actual runtime behavior before choosing a correction.

Add an error response union for an empty title and show how callers discriminate success from failure.

Record expected success and failure outcomes, run the code, and compare the observed behavior. Keep the exercise compatible with strict type checking.

The typed request contains only the title. The function normalizes the text and creates a response with an ID and done field. An HTTP endpoint would also need validation and status codes.

Apply the same reasoning to the practice task, then integrate it into a real app only when the runtime and dependency setup are ready.