API versioning is essential for maintaining stable services while introducing improvements. I’ve implemented numerous versioning strategies across different projects, and I’ll share the most effective approaches.

URL-based versioning remains the most straightforward method. It involves including the version number directly in the endpoint path. Here’s a basic Express.js implementation:

const express = require('express');
const app = express();

// V1 endpoints
app.use('/api/v1', require('./routes/v1'));

// V2 endpoints
app.use('/api/v2', require('./routes/v2'));

// Example V1 route handler
router.get('/users', (req, res) => {
    res.json({ version: '1.0', data: [] });
});

Header-based versioning offers a cleaner URL structure. We can implement it using custom headers:

app.use((req, res, next) => {
    const version = req.headers['api-version'] || '1.0';
    req.apiVersion = version;
    next();
});

app.get('/api/users', (req, res) => {
    if (req.apiVersion === '1.0') {
        return userServiceV1.getUsers();
    }
    return userServiceV2.getUsers();
});

Query parameter versioning provides excellent visibility and ease of testing:

app.get('/api/users', (req, res) => {
    const version = req.query.version || '1.0';
    handleUserRequest(version, req, res);
});

Managing multiple versions requires careful code organization. I recommend using a factory pattern:

class APIFactory {
    static getHandler(version) {
        switch(version) {
            case '2.0':
                return new APIv2Handler();
            default:
                return new APIv1Handler();
        }
    }
}

class BaseAPIHandler {
    async getUsers() {
        throw new Error('Not implemented');
    }
}

class APIv1Handler extends BaseAPIHandler {
    async getUsers() {
        return await db.users.find();
    }
}

class APIv2Handler extends BaseAPIHandler {
    async getUsers() {
        const users = await db.users.find();
        return users.map(user => this.transformUserV2(user));
    }
}

Documentation plays a crucial role in API versioning. I use OpenAPI (Swagger) specifications for each version:

openapi: 3.0.0
info:
  title: User API
  version: 2.0.0
paths:
  /users:
    get:
      parameters:
        - name: api-version
          in: header
          required: true
          schema:
            type: string
            enum: ['1.0', '2.0']
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'

Deprecation policies should be clear and well-communicated. I implement deprecation headers:

app.use('/api/v1/*', (req, res, next) => {
    res.set({
        'Deprecation': 'true',
        'Sunset': 'Sat, 1 Jan 2024 00:00:00 GMT',
        'Link': '</api/v2/docs>; rel="deprecation"; type="text/html"'
    });
    next();
});

Version negotiation helps clients choose the appropriate API version:

app.get('/api', (req, res) => {
    res.json({
        versions: {
            '1.0': {
                status: 'deprecated',
                sunset: '2024-01-01',
                url: '/api/v1'
            },
            '2.0': {
                status: 'current',
                url: '/api/v2'
            }
        }
    });
});

Testing versioned APIs requires comprehensive coverage across versions:

describe('User API', () => {
    const versions = ['1.0', '2.0'];
    
    versions.forEach(version => {
        describe(`Version ${version}`, () => {
            it('should return users', async () => {
                const response = await request(app)
                    .get('/api/users')
                    .set('api-version', version);
                
                expect(response.status).toBe(200);
                
                if (version === '2.0') {
                    expect(response.body).toHaveProperty('metadata');
                }
            });
        });
    });
});

Database schemas often need versioning support:

const userSchema = new mongoose.Schema({
    name: String,
    email: String,
    schemaVersion: {
        type: Number,
        default: 1
    }
});

userSchema.pre('find', function() {
    this.transform = function(doc) {
        if (doc.schemaVersion === 1) {
            return transformV1(doc);
        }
        return transformV2(doc);
    };
});

Error handling should be version-aware:

class APIError extends Error {
    constructor(message, statusCode, version) {
        super(message);
        this.statusCode = statusCode;
        this.version = version;
    }

    toResponse() {
        if (this.version === '1.0') {
            return {
                error: this.message,
                code: this.statusCode
            };
        }
        return {
            error: {
                message: this.message,
                status: this.statusCode,
                timestamp: new Date().toISOString()
            }
        };
    }
}

Monitoring and analytics should track version usage:

app.use((req, res, next) => {
    const version = req.headers['api-version'] || '1.0';
    
    metrics.increment('api.request', {
        version: version,
        endpoint: req.path,
        method: req.method
    });
    
    next();
});

Migration tools help clients transition between versions:

const migrationTools = {
    userDataV1ToV2: (userData) => {
        return {
            ...userData,
            fullName: `${userData.firstName} ${userData.lastName}`,
            contact: {
                email: userData.email,
                phone: userData.phone
            }
        };
    }
};

Feature flags can help manage version transitions:

const featureFlags = {
    async isEnabled(feature, version) {
        const flags = await redis.get(`features:${version}`);
        return flags.includes(feature);
    }
};

app.get('/api/users', async (req, res) => {
    const version = req.headers['api-version'];
    
    if (await featureFlags.isEnabled('enhanced-search', version)) {
        return enhancedSearch(req.query);
    }
    
    return standardSearch(req.query);
});

API versioning requires careful planning and implementation. The chosen strategy should align with your team’s capabilities and your clients’ needs. Regular monitoring, clear documentation, and proper testing ensure smooth version transitions and maintain backward compatibility while enabling innovation.

Through my experience, I’ve found that combining URL-based versioning with clear deprecation policies offers the best balance of simplicity and flexibility. The key is maintaining consistent communication with API consumers and providing adequate migration periods between versions.

Remember that versioning is not just a technical challenge but also a product management decision. The goal is to balance innovation with stability, ensuring your API evolves while supporting existing clients.