Migration Guides

# Migration Guide: v1 to v2

## What Changed
- User response includes 'email' field
- Pagination now uses cursor-based instead of offset
- Authentication requires Bearer token (API key deprecated)

## Before (v1)
GET /v1/users?page=1
Authorization: ApiKey abc123

Response:
{
  "users": [{"id": 1, "name": "Alice"}],
  "total_pages": 5
}

## After (v2)
GET /v2/users?cursor=eyJpZCI6MX0=
Authorization: Bearer eyJhbGciOiJI...

Response:
{
  "data": [{"id": 1, "name": "Alice", "email": "alice@example.com"}],
  "pagination": {"next_cursor": "...", "has_more": true}
}

# Migration script: v1 to v2 response adapter
class V1ToV2Adapter:
    @staticmethod
    def adapt_user_response(v2_user):
        """Convert v2 user response to v1 format."""
        return {
            "id": v2_user["id"],
            "name": v2_user["name"]
            # email removed - v1 didn't have it
        }

    @staticmethod
    def adapt_pagination(v2_pagination):
        """Convert v2 cursor pagination to v1 offset format."""
        return {
            "users": v2_pagination["data"],
            "total_pages": None  # cursor doesn't support total pages
        }

// Migration guide section as a function
function v1toV2MigrationGuide() {
  const changes = [
    {
      id: 'email-field',
      type: 'addition',
      description: 'New email field in user response',
      impact: 'low',
      action: 'Update your user display to show email if desired'
    },
    {
      id: 'pagination-change',
      type: 'breaking',
      description: 'Switched from offset to cursor pagination',
      impact: 'high',
      action: 'Replace page/offset parameters with cursor param'
    },
    {
      id: 'auth-change',
      type: 'breaking',
      description: 'API key deprecated, use Bearer token',
      impact: 'high',
      action: 'Replace ApiKey header with Authorization: Bearer'
    }
  ];

  return changes.filter(c => c.impact === 'high');
}