API Versioning : Gérer les breaking changes sans casser les clients

// V1 API (1000 clients utilisent ça)
GET /api/users/123
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com"
}

// V2 : On veut séparer prénom/nom
GET /api/users/123
{
  "id": 123,
  "firstName": "Alice",  // Breaking change!
  "lastName": "Smith",
  "email": "alice@example.com"
}

// Résultat : 1000 clients cassés

GET /api/users/123
Accept: application/vnd.myapi.v2+json

→ Returns V2 format

GET /api/users/123
Accept: application/vnd.myapi.v1+json

→ Returns V1 format

GET /api/users/123
Accept: application/json; version=2

→ Returns V2

// V1
{
  "id": 123,
  "name": "Alice"
}

// V2 : Ajouter field (backward compatible)
{
  "id": 123,
  "name": "Alice",
  "avatar": "https://..." // Nouveau field, V1 l'ignore
}

// ✅ V1 clients still work

// V1 : Pas de pagination
GET /api/users

// V2 : Pagination avec defaults
GET /api/users
// → Équivalent à GET /api/users?page=1&limit=20

// ✅ V1 clients get default behavior

// V2 : Nouveau field + ancien deprecated
{
  "id": 123,
  "name": "Alice", // @deprecated Use firstName/lastName
  "firstName": "Alice",
  "lastName": "Smith"
}

// Header warning
Warning: 299 - "Field 'name' is deprecated, use 'firstName'/'lastName'"

// V1 interface (legacy)
interface UserV1 {
  id: number;
  name: string;
}

// V2 interface (nouveau)
interface UserV2 {
  id: number;
  firstName: string;
  lastName: string;
}

// Adapter V2 → V1
function toV1(userV2: UserV2): UserV1 {
  return {
    id: userV2.id,
    name: `${userV2.firstName} ${userV2.lastName}`
  };
}

// V1 endpoint utilise V2 data + adapter
app.get('/api/v1/users/:id', async (req, res) => {
  const userV2 = await getUserV2(req.params.id);
  const userV1 = toV1(userV2);
  res.json(userV1);
});

// → V1 maintenu sans code dupliqué

const features = {
  v1: {
    newPagination: false,
    expandedFields: false
  },
  v2: {
    newPagination: true,
    expandedFields: true
  }
};

app.get('/api/:version/users', (req, res) => {
  const version = req.params.version; // 'v1' or 'v2'
  const config = features[version];

  if (config.newPagination) {
    // Nouvelle pagination
  } else {
    // Ancienne pagination
  }
});

// Structure projet
/src
  /v1
    /routes
      users.ts
    /controllers
      users.controller.ts
  /v2
    /routes
      users.ts
    /controllers
      users.controller.ts
  /shared
    /models
      user.model.ts
    /services
      user.service.ts

// app.ts
import express from 'express';
import v1Routes from './v1/routes';
import v2Routes from './v2/routes';

const app = express();

// Mount versions
app.use('/api/v1', v1Routes);
app.use('/api/v2', v2Routes);

// Default to latest version
app.use('/api', v2Routes);

// v1/controllers/users.controller.ts
import { UserService } from '../../shared/services/user.service';
import { toV1Format } from '../adapters/user.adapter';

export class UsersControllerV1 {
  async getUser(req, res) {
    const user = await UserService.findById(req.params.id);

    // Convertir au format V1
    const userV1 = toV1Format(user);

    res.json(userV1);
  }
}

// v2/controllers/users.controller.ts
import { UserService } from '../../shared/services/user.service';

export class UsersControllerV2 {
  async getUser(req, res) {
    const user = await UserService.findById(req.params.id);

    // Format V2 natif
    res.json(user);
  }
}

## Breaking Change Announcement

**What:** User API v2 released
**Why:** Better naming, more fields
**When:** V1 deprecated in 6 months

### Migration guide
[Detailed guide with examples]

### Support
- Slack: #api-migration
- Email: api-support@company.com

HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 1 Jun 2025 12:00:00 GMT
Link: </api/v2/users>; rel="successor-version"

{
  "id": 123,
  "name": "Alice"
}

// Track V1 usage
app.use('/api/v1', (req, res, next) => {
  metrics.increment('api.v1.usage', {
    endpoint: req.path,
    client: req.headers['user-agent']
  });
  next();
});

// Dashboard
┌────────────────────────────────┐
│ V1 API Usage                   │
├────────────────────────────────┤
│ Total calls: 12,500/day        │
│ Unique clients: 45             │
│                                │
│ Top clients still on V1:       │
│ 1. mobile-app (8k calls/day)   │
│ 2. partner-acme (3k)           │
│ 3. legacy-cron (1k)            │
└────────────────────────────────┘

Email to top V1 users:

Subject: Action Required: Migrate to V2 by June 1st

Hi {client_name},

Your app still uses our V1 API (12k calls/day).
V1 will be retired on June 1st, 2025.

Migration guide: [link]
Need help? Schedule call: [calendly]

We're here to help!

// Mois 6 : Retirer V1
app.use('/api/v1', (req, res) => {
  res.status(410).json({
    error: 'V1 API retired',
    message: 'Please migrate to V2',
    guide: 'https://docs.api.com/migration-v1-to-v2'
  });
});

openapi: 3.0.0
info:
  title: My API
  version: 2.0.0

servers:
  - url: https://api.example.com/v2
    description: Current version
  - url: https://api.example.com/v1
    description: Deprecated (sunset 2025-06-01)

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserV2'

components:
  schemas:
    UserV2:
      type: object
      properties:
        id:
          type: integer
        firstName:
          type: string
        lastName:
          type: string

// Test V1 et V2 en parallel
describe('Users API', () => {
  describe('V1', () => {
    it('should return user with name field', async () => {
      const res = await request(app)
        .get('/api/v1/users/123')
        .expect(200);

      expect(res.body).toMatchObject({
        id: 123,
        name: expect.any(String)
      });
    });
  });

  describe('V2', () => {
    it('should return user with firstName/lastName', async () => {
      const res = await request(app)
        .get('/api/v2/users/123')
        .expect(200);

      expect(res.body).toMatchObject({
        id: 123,
        firstName: expect.any(String),
        lastName: expect.any(String)
      });
    });
  });

  describe('V1 → V2 consistency', () => {
    it('should return same data (formatted differently)', async () => {
      const v1 = await request(app).get('/api/v1/users/123');
      const v2 = await request(app).get('/api/v2/users/123');

      expect(v1.body.id).toBe(v2.body.id);
      expect(v1.body.name).toBe(`${v2.body.firstName} ${v2.body.lastName}`);
    });
  });
});

# V1
type User {
  id: ID!
  name: String!
}

# V2 : Ajouter fields sans casser V1
type User {
  id: ID!
  name: String! @deprecated(reason: "Use firstName/lastName")
  firstName: String!
  lastName: String!
}

# V1 clients query
{
  user(id: 123) {
    id
    name  # Encore supporté
  }
}

# V2 clients query
{
  user(id: 123) {
    id
    firstName
    lastName
  }
}