API versioning

The first time you want to rename a field in your API response, you realize that every client depending on the old field will break. Versioning is how you ship breaking changes without taking your users with you. Serve the old version and the new version in parallel for as long as needed.

after/index.ts
typescript
import { bookRouterV1 } from './routes/v1/book.routes';

// V1: the current shape
app.use('/api/v1/books', bookRouterV1);

// Later, when a breaking change is needed:
// app.use('/api/v2/books', bookRouterV2);

Mount versioned routers under /api/v1 so v2 can live alongside it later.

Add the version prefix on day one, even if you only have v1. The cost is zero when you start. The cost of adding versioning later, after clients already depend on unversioned URLs, is enormous. This is one of those rare free upgrades. Take it.

Long enough that every client has a reasonable window to migrate. For public APIs, months to a year. For internal APIs where you control the clients, maybe a sprint. Add a Deprecation header on the old responses, document the sunset date, and actually remove it when the date arrives. Half-removed versions rot.

Quiz: Quiz

Loading practice…