d-subrahmanyam/api-versioning

API Versioning - Quick Reference

When NOT to Use This Skill

• Database schema versioning - Use migration skills
• Feature flags - Use deployment skills
• Contract validation - Use openapi-contract skill

Versioning Strategies

| Strategy | Example | Pros | Cons | |----------|---------|------|------| | URL Path | /api/v1/users | Clear, cacheable | URL changes | | Query Param | /api/users?version=1 | Easy to implement | Not RESTful | | Header | Accept: application/vnd.api.v1+json | Clean URLs | Less visible | | Content Negotiation | Accept: application/json; version=1 | Flexible | Complex |

Recommendation: URL Path Versioning

Most common, easiest to understand, best tooling support.

URL Path Versioning

Backend Implementation (NestJS)

// Version 1 controller
@Controller('api/v1/users')
export class UsersControllerV1 {
  @Get()
  findAll(): UserV1[] {
    return this.usersService.findAllV1();
  }
}

// Version 2 controller
@Controller('api/v2/users')
export class UsersControllerV2 {
  @Get()
  findAll(): UserV2[] {
    return this.usersService.findAllV2();
  }
}

// Or using NestJS built-in versioning
@Controller('users')
@Version('1')
export class UsersControllerV1 { ... }

@Controller('users')
@Version('2')
export class UsersControllerV2 { ... }

Backend Implementation (Spring Boot)

// Version 1 controller
@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 {
    @GetMapping
    public List<UserDtoV1> getUsers() {
        return userService.getUsersV1();
    }
}

// Version 2 controller
@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 {
    @GetMapping
    public List<UserDtoV2> getUsers() {
        return userService.getUsersV2();
    }
}

Frontend Configuration

// api/config.ts
const API_VERSION = process.env.NEXT_PUBLIC_API_VERSION || 'v1';

export const API_BASE_URL = `/api/${API_VERSION}`;

// api/client.ts
import createClient from 'openapi-fetch';
import type { paths } from './types';

const client = createClient<paths>({
  baseUrl: API_BASE_URL,
});

// Usage
const users = await client.GET('/users');  // Calls /api/v1/users

Header Versioning

Backend Implementation

// NestJS with header versioning
app.enableVersioning({
  type: VersioningType.HEADER,
  header: 'X-API-Version',
});

@Controller('users')
@Version('1')
export class UsersControllerV1 { ... }

Frontend Implementation

const api = axios.create({
  baseURL: '/api',
  headers: {
    'X-API-Version': '1',
  },
});

// Or per-request
const response = await fetch('/api/users', {
  headers: {
    'X-API-Version': '2',
  },
});

Version Coexistence

OpenAPI Spec per Version

# openapi-v1.yaml
openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
servers:
  - url: /api/v1

paths:
  /users:
    get:
      responses:
        200:
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserV1'

components:
  schemas:
    UserV1:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

# openapi-v2.yaml
openapi: 3.0.3
info:
  title: My API
  version: 2.0.0
servers:
  - url: /api/v2

paths:
  /users:
    get:
      responses:
        200:
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserV2'

components:
  schemas:
    UserV2:
      type: object
      properties:
        id:
          type: string  # Changed to string!
        firstName:      # Split from name
          type: string
        lastName:       # Split from name
          type: string
        email:
          type: string
        createdAt:      # New field
          type: string
          format: date-time

Generate Types for Both

# Generate v1 types
npx openapi-typescript openapi-v1.yaml -o src/api/v1/types.ts

# Generate v2 types
npx openapi-typescript openapi-v2.yaml -o src/api/v2/types.ts

Frontend Version Support

// api/v1/client.ts
import createClient from 'openapi-fetch';
import type { paths } from './types';

export const clientV1 = createClient<paths>({
  baseUrl: '/api/v1',
});

// api/v2/client.ts
import createClient from 'openapi-fetch';
import type { paths } from './types';

export const clientV2 = createClient<paths>({
  baseUrl: '/api/v2',
});

// Use the appropriate version
import { clientV1 } from './api/v1/client';
import { clientV2 } from './api/v2/client';

// Migrating gradually
const users = await clientV2.GET('/users');  // Use v2 for users
const orders = await clientV1.GET('/orders'); // Still on v1 for orders

Migration Patterns

Adapter Pattern

// Adapt v1 response to v2 format
function adaptUserV1toV2(userV1: UserV1): UserV2 {
  const [firstName, ...lastParts] = userV1.name.split(' ');
  return {
    id: String(userV1.id),  // Convert number to string
    firstName,
    lastName: lastParts.join(' '),
    email: userV1.email,
    createdAt: new Date().toISOString(),  // Default value
  };
}

// Use during migration
async function getUsers(): Promise<UserV2[]> {
  if (USE_V2_API) {
    const { data } = await clientV2.GET('/users');
    return data;
  } else {
    const { data } = await clientV1.GET('/users');
    return data.map(adaptUserV1toV2);
  }
}

Feature Flag Migration

// Gradual rollout with feature flag
async function getUsers(): Promise<User[]> {
  const useV2 = await featureFlags.isEnabled('api-v2-users');

  if (useV2) {
    return fetchUsersV2();
  }
  return fetchUsersV1();
}

Backend Deprecation Headers

// NestJS - Add deprecation warning
@Controller('api/v1/users')
@Header('Deprecation', 'true')
@Header('Sunset', 'Sat, 01 Jan 2025 00:00:00 GMT')
@Header('Link', '</api/v2/users>; rel="successor-version"')
export class UsersControllerV1 { ... }

Frontend Deprecation Handling

axios.interceptors.response.use((response) => {
  if (response.headers['deprecation'] === 'true') {
    const sunset = response.headers['sunset'];
    console.warn(
      `API endpoint ${response.config.url} is deprecated. ` +
      `Will be removed on ${sunset}`
    );
    // Track in analytics
    analytics.track('deprecated_api_used', {
      endpoint: response.config.url,
      sunset,
    });
  }
  return response;
});

Breaking vs Non-Breaking Changes

Non-Breaking (Safe)

| Change | Example | Action | |--------|---------|--------| | Add optional field | createdAt?: string | No version bump | | Add new endpoint | GET /users/search | No version bump | | Add optional param | ?include=profile | No version bump | | Widen response type | id: number \| string | No version bump |

Breaking (Requires New Version)

| Change | Example | Action | |--------|---------|--------| | Remove field | Remove name | New version | | Rename field | name → fullName | New version | | Change type | id: number → id: string | New version | | Change URL | /users → /members | New version | | Add required field | role: string (required) | New version |

Validation Checklist

Per-Endpoint Check

| Check | V1 | V2 | Frontend Uses | Status | |-------|----|----|---------------|--------| | Base URL | /api/v1 | /api/v2 | /api/v1 | OK | | User.id type | number | string | number | MISMATCH | | User.name | present | split | uses name | MISMATCH | | Response structure | same | same | OK | OK |

Migration Readiness

## Migration Readiness Report

### Endpoints Using V1
- GET /api/v1/users (10 components)
- POST /api/v1/users (3 components)
- GET /api/v1/orders (5 components)

### Breaking Changes in V2
1. User.id: number → string
   - Affected: UserCard, UserList, UserProfile
   - Action: Update type definitions

2. User.name → User.firstName + User.lastName
   - Affected: UserCard, UserForm
   - Action: Update display logic

### Migration Plan
1. [ ] Generate V2 types
2. [ ] Create adapter functions
3. [ ] Update components gradually
4. [ ] Switch API client to V2
5. [ ] Remove V1 code

Anti-Patterns

| Anti-Pattern | Why It's Bad | Correct Approach | |--------------|--------------|------------------| | Breaking changes without version | Breaks clients | Create new version | | Mixing v1/v2 in same client | Confusion | Separate clients per version | | No deprecation notice | Surprise breakage | Add sunset headers | | Removing old version immediately | Breaks clients | Sunset period | | Version in domain name | Hard to manage | Use URL path |

Quick Troubleshooting

| Issue | Likely Cause | Solution | |-------|--------------|----------| | Wrong response format | Using wrong version | Check API_VERSION config | | 404 on new endpoint | Still using old version | Update base URL | | Type errors | Types don't match version | Regenerate types | | Deprecation warnings | Using old version | Plan migration | | Mixed responses | Inconsistent version use | Audit all API calls |

Related Skills

• OpenAPI Contract
• Type Generation
• Error Contract