Migrating a REST API to TypeScript

The problem

A Node.js/Express API that had grown organically over three years had no type safety. Runtime errors were making it to production regularly. The frontend team spent significant time debugging issues that turned out to be shape mismatches between what the API promised and what it actually returned.

The codebase had 47 endpoints, no tests, and no documentation.

Starting with the edges

I resisted the temptation to rewrite. Instead, I introduced TypeScript incrementally — starting at the boundary layer: request validation with Zod and typed response schemas. This caught the most common class of errors without requiring a full migration upfront.

Once the boundary was typed, propagating types inward was straightforward. The compiler became the reviewer.

Migration strategy

The migration ran alongside normal product development. Each endpoint was migrated when it was touched for a bug fix or feature, rather than in a dedicated rewrite sprint. This kept the team unblocked and reduced the risk of a big-bang migration.

I also introduced a lightweight test suite — not comprehensive coverage, but enough to pin the behaviour of the 12 highest-traffic endpoints before migration.

The outcome

Full TypeScript coverage reached in 11 weeks. Runtime errors from type mismatches dropped to near zero in production. Bug reports from the frontend team fell 60% over the following two months.

The Zod validation layer also became the source of truth for API documentation — auto-generated and always in sync.