API Versioning — Animate | AI Wisdom

← Back to topic
🎞 ANIMATE · Mode 3 of 5 · +100 XP— API Versioning
📋URL Version
⚙️Schema Changes
🔄Header Version
✅Deprecation
🎯 Next: Test →
Step 1 / 4
Speed
URL Versioning
/api/v1 and /api/v2 coexist — clients choose their version💡 Analogy
Like software versions on a download page — v1.0 and v2.0 are both available; you choose which to use.
URL versioning is the most visible and cacheable approach. Clients explicitly request /api/v2/users. Both versions run simultaneously.
Console Output
> GET /api/v1/users/123 → { id, name }
> GET /api/v2/users/123 → { id, displayName, profile, _links }
> Both routes active simultaneously
●api-versions.ts
URL VersioningL6–25
1// Strategy 1: URL versioning (most common)
2// /api/v1/users  →  /api/v2/users
3import express from 'express';
4const app = express();
5 
6const v1Router = express.Router();
7const v2Router = express.Router();
8 
9// V1: simple user object
10v1Router.get('/users/:id', async (req, res) => {
11  const user = await db.users.findById(req.params.id);
12  res.json({ id: user.id, name: user.name }); // v1 schema
13});
14 
15// V2: rich user object with nested profile
16v2Router.get('/users/:id', async (req, res) => {
17  const user = await db.users.findByIdWithProfile(req.params.id);
18  res.json({
19    id: user.id,
20    displayName: user.name,      // renamed field
21    profile: { avatar: user.avatar, bio: user.bio },
22    _links: { self: `/api/v2/users/${user.id}` }, // HATEOAS
23  });
24});
25 
26app.use('/api/v1', v1Router);
27app.use('/api/v2', v2Router);
28 
29// Strategy 2: Header versioning (content negotiation)
30app.get('/users/:id', (req, res) => {
31  const version = req.headers['api-version'] ?? '1';
32  if (version === '2') {
33    return res.json({ displayName: 'Alice', profile: {} });
34  }
35  return res.json({ name: 'Alice' });
36});
37 
38declare const db: any;
38 lines
Timeline — 4 Steps
URL Versioning
/api/v1 and /api/v2 coexist — clients choose their version💡 Analogy
Like software versions on a download page — v1.0 and v2.0 are both available; you choose which to use.
URL versioning is the most visible and cacheable approach. Clients explicitly request /api/v2/users. Both versions run simultaneously.
Console Output
> GET /api/v1/users/123 → { id, name }
> GET /api/v2/users/123 → { id, displayName, profile, _links }
> Both routes active simultaneously

Was this page helpful?

Discussion

/api/v1 and /api/v2 coexist — clients choose their version

💡 Analogy

Like software versions on a download page — v1.0 and v2.0 are both available; you choose which to use.

URL versioning is the most visible and cacheable approach. Clients explicitly request /api/v2/users. Both versions run simultaneously.

Console Output

> GET /api/v1/users/123 → { id, name }
> GET /api/v2/users/123 → { id, displayName, profile, _links }
> Both routes active simultaneously

/api/v1 and /api/v2 coexist — clients choose their version

💡 Analogy

Like software versions on a download page — v1.0 and v2.0 are both available; you choose which to use.

URL versioning is the most visible and cacheable approach. Clients explicitly request /api/v2/users. Both versions run simultaneously.

Console Output

> GET /api/v1/users/123 → { id, name }
> GET /api/v2/users/123 → { id, displayName, profile, _links }
> Both routes active simultaneously