APIs are easy to create, hard to change, and nearly impossible to remove. Every API endpoint is a contract with consumers, and breaking that contract means breaking their applications. Yet APIs must evolve: business requirements change, better designs emerge, technical debt accumulates.

The hard truth: deprecation is a feature. If you can't deprecate, you can't evolve. Most organizations never think about deprecation until they need it, by which point the API has accumulated years of unknown consumers.

This document covers the full lifecycle of API deprecation: when to deprecate, how to communicate, migration patterns, and the organizational processes that make it work.

The Deprecation Decision Framework

When NOT to Deprecate

Deprecation has real costs: migration effort, consumer disruption, dual maintenance. Don't deprecate for:

Cosmetic reasons: "I don't like the naming convention"
Minor inefficiencies: "This could be 10% faster with a different approach"
Team preference: "The new team prefers REST over GraphQL"

When to Deprecate

Deprecation is justified when:

Security vulnerability that can't be patched backward-compatibly
Fundamental design flaw that limits the API's utility
Unsustainable maintenance burden due to legacy dependencies
Business model change that makes the API obsolete
Consolidation where multiple APIs serve the same purpose

The Cost-Benefit Analysis

Deprecation Cost:
├─ Consumer migration effort (their time)
├─ Support burden during transition
├─ Documentation overhead
├─ Dual maintenance period
└─ Trust erosion if handled poorly

Deprecation Benefit:
├─ Reduced maintenance burden (long-term)
├─ Improved API surface area
├─ Security/compliance requirements met
├─ Consolidation of systems
└─ Technical debt reduction

Decision: Deprecate when long-term benefit exceeds short-term cost × probability of failure

Deprecation Stages

The Deprecation Lifecycle

┌──────────────────────────────────────────────────────────────────────────┐
│                           API Lifecycle                                   │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                           │
│  ACTIVE        DEPRECATED       SUNSET          REMOVED                   │
│  ──────        ──────────       ──────          ───────                   │
│  Full support  Maintenance      Read-only       Gone                      │
│  New features  only             mode                                      │
│  Bug fixes     Security fixes   Critical only                             │
│                Warnings issued  Rate limited                              │
│                Migration path   Errors returned                           │
│                                                                           │
│  ─────────────────────────────────────────────────────────────────────── │
│                                                                           │
│  Timeline example:                                                        │
│  │                                                                        │
│  │  Jan 2024    │  Jul 2024    │  Jan 2025    │  Jul 2025               │
│  │  ▼           │  ▼           │  ▼           │  ▼                       │
│  │  Announce    │  Deprecated  │  Sunset      │  Removed                 │
│  │  deprecation │  status      │  begins      │                          │
│  │              │  active      │              │                          │
│  │                                                                        │
└──────────────────────────────────────────────────────────────────────────┘

Stage 1: Active with Deprecation Warning

API still works fully but warns consumers.

// Server-side: Add deprecation headers
app.get('/api/v1/users', (req, res) => {
  res.setHeader('Deprecation', 'true');
  res.setHeader('Sunset', 'Sat, 01 Jul 2025 00:00:00 GMT');
  res.setHeader(
    'Link',
    '</api/v2/users>; rel="successor-version"'
  );

  // Normal response
  return res.json(users);
});

// Client-side: Detect and warn
async function apiClient(url: string, options?: RequestInit) {
  const response = await fetch(url, options);

  // Check for deprecation
  if (response.headers.get('Deprecation') === 'true') {
    const sunset = response.headers.get('Sunset');
    const successor = response.headers.get('Link');

    console.warn(
      `API Deprecation Warning: ${url}\n` +
      `Sunset date: ${sunset}\n` +
      `Successor: ${successor}`
    );

    // Report to monitoring
    analytics.track('deprecated_api_called', {
      endpoint: url,
      sunset,
      successor,
    });
  }

  return response;
}

Stage 2: Deprecated with Rate Limiting

Reduce traffic to encourage migration.

// Gradually reduce rate limits as sunset approaches
function getDeprecatedRateLimit(endpoint: string, sunsetDate: Date): number {
  const now = new Date();
  const totalDays = differenceInDays(sunsetDate, DEPRECATION_ANNOUNCED);
  const daysRemaining = differenceInDays(sunsetDate, now);
  const progress = 1 - (daysRemaining / totalDays);

  // Start at 100%, linearly decrease to 10% at sunset
  const rateMultiplier = Math.max(0.1, 1 - (progress * 0.9));

  return Math.floor(NORMAL_RATE_LIMIT * rateMultiplier);
}

// Apply in middleware
app.use('/api/v1/*', (req, res, next) => {
  const limit = getDeprecatedRateLimit(req.path, SUNSET_DATE);
  rateLimiter.setLimit(limit);
  next();
});

Stage 3: Sunset Mode

API returns errors with migration guidance.

// After sunset date
app.use('/api/v1/*', (req, res) => {
  // Log for analytics
  logger.info('Sunset API called', {
    endpoint: req.path,
    consumer: req.headers['x-api-key'],
    userAgent: req.headers['user-agent'],
  });

  res.status(410).json({
    error: {
      code: 'API_SUNSET',
      message: 'This API version has been sunset.',
      migration: {
        documentation: 'https://docs.example.com/migration/v1-to-v2',
        newEndpoint: req.path.replace('/api/v1', '/api/v2'),
        support: 'api-support@example.com',
      },
    },
  });
});

Stage 4: Removal

API endpoints no longer exist.

// Return 404 with helpful message
app.use('/api/v1/*', (req, res) => {
  res.status(404).json({
    error: {
      code: 'API_REMOVED',
      message: 'API v1 has been removed. Please use v2.',
      documentation: 'https://docs.example.com/api/v2',
    },
  });
});

Migration Pattern 1: Versioned Endpoints

URL Versioning

/api/v1/users      → deprecated
/api/v2/users      → active
/api/v3/users      → beta

// Version routing middleware
const routers: Record<string, Router> = {
  v1: legacyRouter,  // Maintenance mode
  v2: currentRouter, // Active development
  v3: betaRouter,    // Early access
};

app.use('/api/:version', (req, res, next) => {
  const version = req.params.version;

  if (version === 'v1') {
    // Add deprecation headers
    res.setHeader('Deprecation', 'true');
    res.setHeader('Sunset', 'Sat, 01 Jul 2025 00:00:00 GMT');
  }

  const router = routers[version];
  if (!router) {
    return res.status(404).json({ error: 'API version not found' });
  }

  router(req, res, next);
});

Header Versioning

// Accept-Version header
app.use('/api/*', (req, res, next) => {
  const version = req.headers['accept-version'] || 'v2'; // default to latest

  if (version === 'v1') {
    res.setHeader('Deprecation', 'true');
    req.apiVersion = 'v1';
  } else {
    req.apiVersion = version;
  }

  next();
});

// Route handlers check version
app.get('/api/users', (req, res) => {
  if (req.apiVersion === 'v1') {
    return res.json(formatV1Response(users));
  }
  return res.json(formatV2Response(users));
});

Migration Pattern 2: Adapter Layer

For frontend applications consuming the deprecated API, introduce an adapter.

The Adapter Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                          Frontend Application                            │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                         API Client                                │   │
│  │  ┌────────────────────────────────────────────────────────────┐  │   │
│  │  │                    Adapter Layer                           │  │   │
│  │  │                                                            │  │   │
│  │  │  V1 Response Shape  ←──transform──  V2 Response Shape      │  │   │
│  │  │  { name: string }                   { fullName: string }   │  │   │
│  │  │                                                            │  │   │
│  │  └────────────────────────────────────────────────────────────┘  │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                      │                                   │
└──────────────────────────────────────┼───────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                            API Server                                    │
│                                                                          │
│  /api/v2/users  (new format)                                            │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Implementation

// api/adapters/user.adapter.ts

// Old interface (what app currently expects)
interface V1User {
  id: string;
  name: string;
  email: string;
  created_at: string;
}

// New interface (what API v2 returns)
interface V2User {
  id: string;
  fullName: string;
  emailAddress: string;
  createdAt: string;
  metadata: {
    source: string;
    verified: boolean;
  };
}

// Adapter transforms v2 to v1 shape
function adaptV2ToV1(v2User: V2User): V1User {
  return {
    id: v2User.id,
    name: v2User.fullName,           // renamed field
    email: v2User.emailAddress,       // renamed field
    created_at: v2User.createdAt,     // format change (snake_case to camelCase)
  };
}

// Gradual migration: feature flag controls which version
async function getUser(id: string): Promise<V1User> {
  const flags = await getFeatureFlags();

  if (flags.useV2Api) {
    const response = await fetch(`/api/v2/users/${id}`);
    const v2User: V2User = await response.json();
    return adaptV2ToV1(v2User);  // App doesn't know it's v2
  }

  // Fallback to v1
  const response = await fetch(`/api/v1/users/${id}`);
  return response.json();
}

Migration Phases with Adapter

Phase 1: Introduce adapter, route through v2
┌──────────────┐     ┌─────────┐     ┌────────┐
│ App (V1 API) │────▶│ Adapter │────▶│ V2 API │
└──────────────┘     └─────────┘     └────────┘
  No changes        Transforms       New API
  needed            responses

Phase 2: Incrementally update app to use V2 types
┌──────────────┐     ┌─────────┐     ┌────────┐
│ App (mixed)  │────▶│ Adapter │────▶│ V2 API │
└──────────────┘     └─────────┘     └────────┘
  Some components    Still needed    New API
  use V2 types       for V1 types

Phase 3: Remove adapter, app fully on V2
┌──────────────┐                      ┌────────┐
│ App (V2 API) │─────────────────────▶│ V2 API │
└──────────────┘                      └────────┘
  All V2 types      Adapter removed   New API

Migration Pattern 3: Shadow Traffic Comparison

Before fully switching, validate the new API returns correct data.

// api/middleware/shadow-compare.ts

interface ComparisonResult {
  endpoint: string;
  v1Response: unknown;
  v2Response: unknown;
  match: boolean;
  diff?: object;
}

async function compareEndpoints(req: Request): Promise<ComparisonResult> {
  const v1Url = `/api/v1${req.path}`;
  const v2Url = `/api/v2${req.path}`;

  const [v1Response, v2Response] = await Promise.all([
    fetch(v1Url, { headers: req.headers }),
    fetch(v2Url, { headers: req.headers }),
  ]);

  const [v1Data, v2Data] = await Promise.all([
    v1Response.json(),
    v2Response.json(),
  ]);

  // Normalize for comparison (handle known differences)
  const v1Normalized = normalizeV1Response(v1Data);
  const v2Normalized = normalizeV2Response(v2Data);

  const match = deepEqual(v1Normalized, v2Normalized);

  return {
    endpoint: req.path,
    v1Response: v1Data,
    v2Response: v2Data,
    match,
    diff: match ? undefined : generateDiff(v1Normalized, v2Normalized),
  };
}

// Run comparison for percentage of traffic
app.use('/api/v1/*', async (req, res, next) => {
  if (shouldShadowCompare(req)) {
    const comparison = await compareEndpoints(req);

    if (!comparison.match) {
      logger.warn('API version mismatch', comparison);
      metrics.increment('api.version.mismatch', {
        endpoint: req.path,
      });
    }
  }

  next();
});

Communication Patterns

The Deprecation Timeline Communication

# API v1 Deprecation Notice

## Timeline

| Date | Milestone | Action |
|------|-----------|--------|
| Jan 2024 | Announcement | Deprecation notice published |
| Feb 2024 | Headers Active | Deprecation headers added to responses |
| Apr 2024 | Warnings | Console warnings in SDKs |
| Jul 2024 | Rate Limiting | V1 rate limits reduced by 50% |
| Oct 2024 | Read-Only | V1 becomes read-only |
| Jan 2025 | Sunset | V1 returns 410 errors |
| Apr 2025 | Removal | V1 endpoints removed |

## Migration Guide

See [V1 to V2 Migration Guide](./migration-v1-v2.md)

## Support

- Email: api-deprecation@example.com
- Slack: #api-migration
- Office Hours: Thursdays 2-3pm PT

Consumer-Specific Outreach

// Identify top consumers of deprecated endpoints
async function identifyConsumersNeedingOutreach(): Promise<Consumer[]> {
  const consumers = await db.query(`
    SELECT
      api_key,
      consumer_name,
      SUM(request_count) as total_requests,
      MAX(last_request_at) as last_request,
      array_agg(DISTINCT endpoint) as endpoints
    FROM api_usage_logs
    WHERE
      endpoint LIKE '/api/v1/%'
      AND request_at > NOW() - INTERVAL '30 days'
    GROUP BY api_key, consumer_name
    ORDER BY total_requests DESC
    LIMIT 100
  `);

  return consumers.map(c => ({
    ...c,
    priority: calculateOutreachPriority(c),
  }));
}

// Send targeted communication
async function sendDeprecationNotice(consumer: Consumer) {
  await email.send({
    to: consumer.contactEmail,
    template: 'api-deprecation-notice',
    data: {
      consumerName: consumer.name,
      affectedEndpoints: consumer.endpoints,
      requestVolume: consumer.totalRequests,
      sunsetDate: SUNSET_DATE,
      migrationGuide: MIGRATION_GUIDE_URL,
      supportContact: SUPPORT_EMAIL,
    },
  });

  await db.insert('deprecation_outreach', {
    consumerId: consumer.id,
    sentAt: new Date(),
    endpoints: consumer.endpoints,
  });
}

In-SDK Warnings

// @company/api-sdk

class APIClient {
  private warnedEndpoints = new Set<string>();

  async request(endpoint: string, options?: RequestOptions) {
    const response = await fetch(endpoint, options);

    // Check deprecation header
    if (response.headers.get('Deprecation') === 'true') {
      this.warnAboutDeprecation(endpoint, response);
    }

    return response;
  }

  private warnAboutDeprecation(endpoint: string, response: Response) {
    // Warn once per endpoint per session
    if (this.warnedEndpoints.has(endpoint)) return;
    this.warnedEndpoints.add(endpoint);

    const sunset = response.headers.get('Sunset');
    const successor = this.parseSuccessorLink(response.headers.get('Link'));

    console.warn(
      `%c⚠️ Deprecation Warning`,
      'color: orange; font-weight: bold;',
      `\n\nThe endpoint ${endpoint} is deprecated.` +
      `\nSunset date: ${sunset}` +
      `\nMigrate to: ${successor}` +
      `\nDocs: https://docs.example.com/migration`
    );

    // For Node.js/backend, also emit event
    if (typeof process !== 'undefined') {
      process.emitWarning(
        `Deprecated API endpoint: ${endpoint}. Sunset: ${sunset}`,
        'DeprecationWarning'
      );
    }
  }
}

Measuring Migration Progress

Migration Dashboard

┌─────────────────────────────────────────────────────────────────────────┐
│                   API V1 → V2 Migration Progress                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Overall Progress                                                        │
│  ████████████████████░░░░░░░░░░ 65%                                     │
│                                                                          │
│  Traffic Distribution                                                    │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  V1: ███████████████░░░░░░░░░░░░░░░░░░░░░░░░░  35%              │   │
│  │  V2: █████████████████████████░░░░░░░░░░░░░░░  65%              │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                          │
│  Top V1 Consumers (blocking migration)                                  │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  Consumer         │ V1 Requests/day │ Status      │ Contact     │   │
│  │  ─────────────────────────────────────────────────────────────  │   │
│  │  mobile-app       │ 1.2M            │ In Progress │ @mobile     │   │
│  │  partner-acme     │ 500K            │ Not Started │ @bizdev     │   │
│  │  internal-tool    │ 200K            │ Blocked     │ @platform   │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                          │
│  Timeline                                                                │
│  │                                                                       │
│  │  ●────────●────────●────────○────────○                               │
│  │  Jan     Mar      Jun      Sep      Dec                              │
│  │  ↑        ↑        ↑        ↑        ↑                               │
│  │  Start   50%     Target   Buffer   Sunset                            │
│  │          (actual) 80%     period                                      │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Metrics to Track

interface MigrationMetrics {
  // Traffic split
  v1RequestsPerDay: number;
  v2RequestsPerDay: number;
  migrationPercentage: number;

  // Consumer status
  totalConsumers: number;
  migratedConsumers: number;
  inProgressConsumers: number;
  notStartedConsumers: number;

  // Error rates (ensure v2 is stable)
  v1ErrorRate: number;
  v2ErrorRate: number;

  // Timeline adherence
  targetMigrationDate: Date;
  projectedCompletionDate: Date;
  onTrack: boolean;
}

Failure Modes and Mitigations

Failure Mode 1: Zombie Consumers

Problem: Unknown consumers keep using deprecated API.

Solution: Require API key registration, track all consumers.

// Require identification for API access
app.use('/api/*', (req, res, next) => {
  const apiKey = req.headers['x-api-key'];
  const userAgent = req.headers['user-agent'];

  if (!apiKey) {
    return res.status(401).json({
      error: 'API key required. Register at https://api.example.com/register',
    });
  }

  // Log usage for tracking
  trackApiUsage(apiKey, userAgent, req.path);

  next();
});

Failure Mode 2: Migration Breaks Consumers

Problem: V2 API has subtle differences that break consumer apps.

Solution: Shadow traffic comparison before switching.

Failure Mode 3: Indefinite Deprecation

Problem: Deprecation announced but never enforced.

Solution: Hard sunset date with executive commitment.

## Deprecation Commitment

This deprecation timeline is committed at the VP level:

- **No extensions** without VP approval
- **Sunset date is final** once announced
- **Monthly reviews** of migration progress
- **Escalation path** for blocked consumers

Summary

API deprecation requires treating it as a feature, not an afterthought:

Plan the full lifecycle: Active → Deprecated → Sunset → Removed
Communicate relentlessly: Headers, SDKs, email, dashboards
Provide migration tools: Adapters, guides, shadow comparison
Track progress: Know every consumer, their status, blockers
Enforce the timeline: Soft dates become no dates

The goal is not to deprecate APIs — it's to evolve your platform while maintaining consumer trust.

What did you think?