# Version in path
/api/v1/users        # Current stable
/api/v2/users        # New version
/api/v3-beta/users   # Pre-release

# Version-specific routing
app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

# Request
Accept: application/vnd.myapi.v1+json

# Response
Content-Type: application/vnd.myapi.v1+json

# Sunset header
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Deprecation: true
Link: </api/v2/users>; rel="successor-version"

# Response body warning
{
  "data": {...},
  "warnings": [
    {
      "type": "deprecation",
      "message": "This endpoint is deprecated. Use /api/v2/users instead.",
      "sunset": "2025-12-31"
    }
  ]
}

# Migration from v1 to v2

## Breaking Changes

### User endpoint
- `GET /api/v1/users/{id}` → `GET /api/v2/users/{id}`
- Response field `fullName` renamed to `name`

### Before (v1)
{
  "id": "123",
  "fullName": "John Doe"
}

### After (v2)
{
  "id": "123",
  "name": "John Doe"
}

## Timeline
- v2 available: January 2025
- v1 deprecated: March 2025
- v1 removed: December 2025

describe('API Versioning', () => {
  it('should route to v1 handler', async () => {
    await request(app)
      .get('/api/v1/users')
      .expect(200);
  });

  it('should include deprecation headers for old version', async () => {
    const res = await request(app)
      .get('/api/v1/users')
      .expect(200);

    expect(res.headers.deprecation).toBe('true');
    expect(res.headers.sunset).toBeDefined();
  });
});