Part 6: API Documentation and Versioning

The Undocumented API Nightmare

Six months into my first microservices project, I went on vacation. When I returned, the team had integrated 3 new services with my user API. Each integration was different:

• Frontend team: Sending userId in body

• Mobile team: Sending user_id in body

• Analytics team: Sending id in query params

Why? No documentation. They guessed. All three guesses were wrong—I expected userId in URL params.

We spent 2 days fixing integrations. I spent the weekend writing API documentation.

Lesson learned: Undocumented APIs create more problems than writing documentation ever will.

This article shows how I document and version APIs now.

Swagger/OpenAPI

OpenAPI is the standard for REST API documentation. Swagger provides tools to generate and display it.

Setup

npm install swagger-jsdoc swagger-ui-express
npm install -D @types/swagger-jsdoc @types/swagger-ui-express

Swagger Configuration

// src/config/swagger.ts
import swaggerJsdoc from 'swagger-jsdoc';
import { config } from './environment';

const options: swaggerJsdoc.Options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'User Service API',
      version: '1.0.0',
      description: 'REST API for user management',
      contact: {
        name: 'API Support',
        email: '[email protected]',
      },
      license: {
        name: 'MIT',
        url: 'https://opensource.org/licenses/MIT',
      },
    },
    servers: [
      {
        url: `http://localhost:${config.port}/api/v1`,
        description: 'Development server',
      },
      {
        url: 'https://api.staging.example.com/api/v1',
        description: 'Staging server',
      },
      {
        url: 'https://api.example.com/api/v1',
        description: 'Production server',
      },
    ],
    components: {
      securitySchemes: {
        BearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
          description: 'Enter your JWT token',
        },
      },
      schemas: {
        User: {
          type: 'object',
          properties: {
            id: {
              type: 'string',
              example: 'user_123',
            },
            email: {
              type: 'string',
              format: 'email',
              example: '[email protected]',
            },
            name: {
              type: 'string',
              example: 'John Doe',
            },
            role: {
              type: 'string',
              enum: ['user', 'admin', 'manager'],
              example: 'user',
            },
            createdAt: {
              type: 'string',
              format: 'date-time',
            },
          },
        },
        CreateUserRequest: {
          type: 'object',
          required: ['email', 'password', 'name'],
          properties: {
            email: {
              type: 'string',
              format: 'email',
            },
            password: {
              type: 'string',
              minLength: 8,
            },
            name: {
              type: 'string',
              minLength: 2,
            },
          },
        },
        ErrorResponse: {
          type: 'object',
          properties: {
            success: {
              type: 'boolean',
              example: false,
            },
            error: {
              type: 'string',
              example: 'Resource not found',
            },
          },
        },
      },
    },
    security: [
      {
        BearerAuth: [],
      },
    ],
  },
  apis: ['./src/routes/*.ts', './src/controllers/*.ts'],
};

export const swaggerSpec = swaggerJsdoc(options);

Setup Swagger UI

// src/app.ts
import swaggerUi from 'swagger-ui-express';
import { swaggerSpec } from './config/swagger';

export class App {
  private setupDocs(): void {
    // Swagger UI
    this.app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec, {
      customCss: '.swagger-ui .topbar { display: none }',
      customSiteTitle: 'User Service API Docs',
    }));

    // Swagger JSON
    this.app.get('/api-docs.json', (req, res) => {
      res.json(swaggerSpec);
    });
  }
}

Document Endpoints with JSDoc

// src/routes/user-routes.ts

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     description: Retrieve a list of all users (admin only)
 *     tags: [Users]
 *     security:
 *       - BearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           minimum: 1
 *           default: 1
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           minimum: 1
 *           maximum: 100
 *           default: 20
 *         description: Items per page
 *     responses:
 *       200:
 *         description: List of users
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 data:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/User'
 *                 meta:
 *                   type: object
 *                   properties:
 *                     page:
 *                       type: integer
 *                     limit:
 *                       type: integer
 *                     total:
 *                       type: integer
 *       401:
 *         description: Unauthorized
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       403:
 *         description: Forbidden - Admin access required
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 */
router.get('/', controller.getAllUsers.bind(controller));

/**
 * @swagger
 * /users/{id}:
 *   get:
 *     summary: Get user by ID
 *     description: Retrieve a specific user by their ID
 *     tags: [Users]
 *     security:
 *       - BearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *         description: User ID
 *     responses:
 *       200:
 *         description: User found
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 data:
 *                   $ref: '#/components/schemas/User'
 *       404:
 *         description: User not found
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 */
router.get('/:id', controller.getUserById.bind(controller));

/**
 * @swagger
 * /users:
 *   post:
 *     summary: Create new user
 *     description: Create a new user account
 *     tags: [Users]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/CreateUserRequest'
 *     responses:
 *       201:
 *         description: User created successfully
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 data:
 *                   $ref: '#/components/schemas/User'
 *       422:
 *         description: Validation failed
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: false
 *                 error:
 *                   type: string
 *                   example: Validation failed
 *                 errors:
 *                   type: array
 *                   items:
 *                     type: object
 *                     properties:
 *                       field:
 *                         type: string
 *                       message:
 *                         type: string
 */
router.post('/', controller.createUser.bind(controller));

Automated Documentation with TypeScript Decorators

For cleaner code, use swagger-autogen or typescript-openapi:

npm install swagger-autogen

// scripts/generate-docs.ts
import swaggerAutogen from 'swagger-autogen';

const doc = {
  info: {
    title: 'User Service API',
    description: 'Auto-generated API documentation',
  },
  host: 'localhost:4000',
  schemes: ['http'],
};

const outputFile = './swagger-output.json';
const endpointsFiles = ['./src/routes/*.ts'];

swaggerAutogen()(outputFile, endpointsFiles, doc);

API Versioning Strategies

1. URL Path Versioning (Recommended)

Pros: Clear, cache-friendly, easy routing Cons: URL changes with each version

// src/app.ts
const app = express();

// Version 1
app.use('/api/v1/users', v1UserRoutes);
app.use('/api/v1/products', v1ProductRoutes);

// Version 2 (breaking changes)
app.use('/api/v2/users', v2UserRoutes);
app.use('/api/v2/products', v2ProductRoutes);

Directory structure:

src/
├── v1/
│   ├── controllers/
│   ├── services/
│   └── routes/
├── v2/
│   ├── controllers/
│   ├── services/
│   └── routes/

Example evolution:

// v1/types/user.ts
export interface User {
  id: string;
  name: string;  // Full name
  email: string;
}

// v2/types/user.ts
export interface User {
  id: string;
  firstName: string;  // Split name
  lastName: string;
  email: string;
}

// v2/controllers/user-controller.ts
export class UserControllerV2 {
  async getUser(req: Request, res: Response): Promise<void> {
    const user = await this.userService.getUserById(req.params.id);
    
    // Return v2 format
    res.json({
      success: true,
      data: {
        id: user.id,
        firstName: user.firstName,
        lastName: user.lastName,
        email: user.email,
      },
    });
  }
}

2. Header Versioning

// src/middleware/version-middleware.ts
export class VersionMiddleware {
  static extractVersion(req: Request, res: Response, next: NextFunction) {
    const version = req.headers['api-version'] as string || 'v1';
    
    if (!['v1', 'v2'].includes(version)) {
      return res.status(400).json({
        success: false,
        error: 'Invalid API version. Supported: v1, v2',
      });
    }
    
    req.apiVersion = version;
    next();
  }
}

// Router based on version
app.use('/api/users', VersionMiddleware.extractVersion, (req, res, next) => {
  if (req.apiVersion === 'v2') {
    return v2UserRouter(req, res, next);
  }
  return v1UserRouter(req, res, next);
});

Client usage:

curl -H "API-Version: v2" https://api.example.com/users

3. Query Parameter Versioning

app.get('/api/users', (req, res) => {
  const version = req.query.version || 'v1';
  
  if (version === 'v2') {
    return getUsersV2(req, res);
  }
  return getUsersV1(req, res);
});

Usage:

GET /api/users?version=v2

Migration Strategies

Dual-Write Pattern

Support both versions during transition:

// src/services/user-service.ts
export class UserService {
  async createUser(userData: any): Promise<any> {
    // Normalize to internal format
    const internal = this.normalizeUserData(userData);
    
    // Write to database
    const user = await this.userRepository.create(internal);
    
    // Return in requested version format
    if (req.apiVersion === 'v2') {
      return this.toV2Format(user);
    }
    return this.toV1Format(user);
  }
  
  private normalizeUserData(data: any): InternalUser {
    // Handle both v1 and v2 input formats
    if (data.firstName && data.lastName) {
      // V2 format
      return {
        firstName: data.firstName,
        lastName: data.lastName,
        email: data.email,
      };
    }
    
    // V1 format - split name
    const [firstName, ...lastNameParts] = data.name.split(' ');
    return {
      firstName,
      lastName: lastNameParts.join(' '),
      email: data.email,
    };
  }
}

Deprecation Headers

// src/middleware/deprecation-middleware.ts
export class DeprecationMiddleware {
  static markDeprecated(version: string, sunsetDate: string) {
    return (req: Request, res: Response, next: NextFunction) => {
      res.setHeader('Deprecation', 'true');
      res.setHeader('Sunset', sunsetDate);
      res.setHeader('Link', `</api/${version}>; rel="deprecated-by"`);
      next();
    };
  }
}

// Apply to v1 routes
app.use(
  '/api/v1',
  DeprecationMiddleware.markDeprecated('v2', '2026-12-31'),
  v1Routes
);

Changelog

Maintain a changelog to communicate changes:

# API Changelog

## Version 2.0.0 (2026-02-01)

### Breaking Changes
- `/users` endpoint now returns `firstName` and `lastName` instead of `name`
- Authentication now requires `Bearer` token (was `Token`)
- Removed `/users/search` endpoint (use `/users?query=...` instead)

### New Features
- Added `/users/:id/orders` endpoint
- Added pagination to `/products` endpoint
- Added rate limiting (100 req/15min)

### Bug Fixes
- Fixed user creation validation
- Fixed order total calculation

### Deprecated
- v1 API will be sunset on 2026-12-31
- Migrate to v2 before this date

## Version 1.2.0 (2025-11-15)

### New Features
- Added `/products/:id/reviews` endpoint
- Added search functionality to `/users`

### Bug Fixes
- Fixed password hashing

...

Key Takeaways

1. Document from day one using OpenAPI/Swagger

2. Use URL path versioning for clarity

3. Never remove endpoints without deprecation period

4. Communicate changes via changelog and headers

5. Support old versions for at least 6-12 months

6. Test both versions in CI/CD

7. Use semantic versioning (major.minor.patch)

8. Breaking changes = new major version

9. Mark deprecated endpoints with headers

10. Automate documentation generation when possible

Next in series: Testing, Performance, and Production Deployment—ensuring your API works reliably at scale.

---

Good documentation saves time. Version carefully to avoid breaking client integrations.