JSON Migration & Versioning — Evolving Schemas Without Breaking Clients

1GET /v1/users/42    → {"name": "Alice", "email": "[email protected]"}
2GET /v2/users/42    → {"fullName": "Alice Chen", "email": "[email protected]", "role": "admin"}

1GET /users/42
2Accept: application/vnd.myapi.v2+json
3
4# Or custom header
5GET /users/42
6X-API-Version: 2

1GET /users/42
2Stripe-Version: 2026-04-02
3
4# API key is pinned to a version at creation time
5# Requests without explicit version use the pinned version

1{
2  "name": "Alice Chen",
3  "fullName": "Alice Chen",
4  "email": "[email protected]",
5  "_deprecations": {
6    "name": "Use 'fullName' instead. 'name' will be removed on 2026-09-01."
7  }
8}

1interface User {
2  id: number;
3  fullName: string;
4  email: string;
5  role: string;
6}
7
8function serializeUser(user: User, version: number) {
9  if (version === 1) {
10    return {
11      id: user.id,
12      name: user.fullName,  // v1 clients expect "name"
13      email: user.email,
14    };
15  }
16
17  return {
18    id: user.id,
19    fullName: user.fullName,
20    email: user.email,
21    role: user.role,
22  };
23}

1interface V1User {
2  name: string;
3  email: string;
4  address: string;   // flat string in v1
5}
6
7interface V2User {
8  fullName: string;
9  email: string;
10  address: {         // structured object in v2
11    street: string;
12    city: string;
13    country: string;
14  };
15}
16
17function migrateV1ToV2(v1: V1User): V2User {
18  const parts = v1.address.split(', ');
19  return {
20    fullName: v1.name,
21    email: v1.email,
22    address: {
23      street: parts[0] ?? '',
24      city: parts[1] ?? '',
25      country: parts[2] ?? '',
26    },
27  };
28}