API Versioning

ELI5 — The Vibe Check

API versioning is how you update your API without breaking everyone's apps. It's like releasing a new phone model — the old one still works, but the new one has better features. You put /v1/ or /v2/ in the URL so clients can upgrade when they're ready.

Real Talk

API versioning is the practice of maintaining multiple versions of an API simultaneously to ensure backward compatibility. Common strategies include URL path versioning (/v1/users), header versioning (Accept: application/vnd.api.v2+json), and query parameter versioning (?version=2). It allows API evolution without breaking existing consumers.

Show Me The Code

// URL path versioning
app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

// Header versioning
app.use((req, res, next) => {
  req.apiVersion = req.headers['api-version'] || 'v1';
  next();
});

When You'll Hear This

"We need to version the API before releasing the breaking change." / "v1 returns an array, v2 returns a paginated object — both still work."