Versioning

API Versioning Skill

Purpose

Choose and implement API versioning strategies.

Versioning Strategies

URL Versioning (Recommended)

# 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);

Header Versioning

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

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

Deprecation Policy

# 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"
    }
  ]
}

Breaking vs Non-Breaking Changes

Non-Breaking (Safe)

• Adding new endpoints
• Adding optional fields
• Adding new enum values
• Relaxing validation

Breaking (Requires New Version)

• Removing endpoints
• Removing/renaming fields
• Changing field types
• Tightening validation
• Changing response structure

Migration Guide Template

# 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

Unit Test Template

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();
  });
});

Troubleshooting

Quality Checklist

• Versioning strategy documented
• Deprecation policy defined
• Sunset headers implemented
• Migration guides published
• Version changelog maintained