Active → Deprecated → Sunset → Removed

Active: Fully supported
Deprecated: Still works, but discouraged (6-12 months)
Sunset: Stops working
Removed: Code deleted

Jan 2024: API v1 active
Jun 2024: API v1 deprecated (announce v2)
Dec 2024: API v1 sunset (stops working)
Jan 2025: API v1 code removed

Deploy new version
→ Old endpoint removed
→ Users break immediately
→ Angry customers
→ Emergency rollback

Announce deprecation (6 months notice)
→ Users migrate gradually
→ Sunset date arrives
→ No surprises

Month 0: Announce deprecation
Month 3: 25% migrated
Month 6: 50% migrated
Month 9: 75% migrated
Month 12: 100% migrated, sunset

Month 0: Announce deprecation
Month 3: Reminder + usage stats
Month 6: Final warning
Month 9: Reach out to remaining users
Month 12: Sunset

/**
 * @deprecated Use getUser() instead. Will be removed in v2.0.0.
 * @see getUser
 */
function getUserProfile(id) {
  console.warn('getUserProfile is deprecated. Use getUser() instead.');
  return getUser(id);
}

import warnings

def get_user_profile(id):
    """
    .. deprecated:: 1.5.0
       Use :func:`get_user` instead.
    """
    warnings.warn(
        "get_user_profile is deprecated. Use get_user() instead.",
        DeprecationWarning,
        stacklevel=2
    )
    return get_user(id)

## GET /users/:id/profile

**⚠️ DEPRECATED:** This endpoint is deprecated and will be removed on December 31, 2024.

**Use instead:** `GET /users/:id`

**Migration guide:** https://docs.example.com/migration/profile-to-user

Subject: Deprecation Notice: /users/:id/profile endpoint

Hi developers,

We're deprecating the /users/:id/profile endpoint.

What's changing:
- Endpoint: GET /users/:id/profile
- Sunset date: December 31, 2024
- Replacement: GET /users/:id

Why:
- Consolidating user endpoints for simplicity
- New endpoint provides more data

Action required:
- Update your integration by December 31, 2024
- See migration guide: https://docs.example.com/migration

Need help?
- Reply to this email
- Join office hours: Fridays 2-3pm PT

Thank you,
API Team

# Deprecation Notice: /users/:id/profile Endpoint

**Date:** June 1, 2024
**Sunset Date:** December 31, 2024

We're deprecating the `/users/:id/profile` endpoint in favor of the consolidated `/users/:id` endpoint.

## What's Changing
The `/users/:id/profile` endpoint will stop working on December 31, 2024.

## Why
We're consolidating user endpoints to simplify our API and provide a better developer experience.

## What to Use Instead
Use `GET /users/:id` instead. It returns the same data plus additional fields.

## Migration Guide
See our [migration guide](https://docs.example.com/migration) for step-by-step instructions.

## Timeline
- **June 1, 2024:** Deprecation announced
- **September 1, 2024:** Reminder email sent
- **December 1, 2024:** Final warning
- **December 31, 2024:** Endpoint stops working

## Need Help?
Contact us at api@example.com or join our office hours.

# Changelog

## v1.5.0 (2024-06-01)

### Deprecated
- **GET /users/:id/profile** - Use GET /users/:id instead. Will be removed on 2024-12-31.

### Added
- **GET /users/:id** - New consolidated user endpoint

app.get('/users/:id/profile', (req, res) => {
  // Track usage
  metrics.increment('deprecated.users_profile.calls', {
    client: req.headers['user-agent'],
    clientId: req.user?.clientId
  });
  
  // Return response
  res.json(profile);
});

Deprecated Endpoint: /users/:id/profile
Sunset Date: 2024-12-31 (6 months remaining)

Usage:
- Total calls/day: 1,000 (down from 5,000 last month)
- Unique clients: 50 (down from 200)

Top Clients:
1. mobile-app: 500 calls/day
2. web-app: 300 calls/day
3. partner-api: 200 calls/day

Trend: ↓ Declining (good!)

Subject: Action Required: Migrate from /users/:id/profile

Hi [Client],

We noticed you're still using the deprecated /users/:id/profile endpoint (500 calls/day).

This endpoint will stop working on December 31, 2024 (3 months remaining).

Action required:
- Migrate to GET /users/:id
- See migration guide: https://docs.example.com/migration

Need help?
- Reply to this email
- Schedule a call: https://calendly.com/api-team

Thank you,
API Team

app.get('/users/:id/profile', (req, res) => {
  res.status(410).json({
    error: 'This endpoint has been removed',
    message: 'GET /users/:id/profile was removed on 2024-12-31',
    replacement: 'Use GET /users/:id instead',
    migrationGuide: 'https://docs.example.com/migration'
  });
});

1. Sunset date reached (Dec 31, 2024)
2. Monitor for errors (1 month)
3. If no issues, remove code (Jan 31, 2025)

HTTP/1.1 200 OK
Deprecation: true

HTTP/1.1 200 OK
Sunset: Sat, 31 Dec 2024 23:59:59 GMT

HTTP/1.1 200 OK
Link: <https://docs.example.com/migration>; rel="sunset"

HTTP/1.1 200 OK
Warning: 299 - "This endpoint is deprecated. Use /v2/users instead. See https://docs.example.com/migration"

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Link: <https://docs.example.com/migration>; rel="sunset"
Warning: 299 - "This endpoint is deprecated and will be removed on 2024-12-31. Use /v2/users instead."
Content-Type: application/json

{
  "id": "123",
  "name": "John Doe"
}

function deprecationHeaders(sunsetDate, migrationUrl, message) {
  return (req, res, next) => {
    res.set('Deprecation', 'true');
    res.set('Sunset', sunsetDate);
    res.set('Link', `<${migrationUrl}>; rel="sunset"`);
    res.set('Warning', `299 - "${message}"`);
    next();
  };
}

app.get('/users/:id/profile',
  deprecationHeaders(
    'Sat, 31 Dec 2024 23:59:59 GMT',
    'https://docs.example.com/migration',
    'This endpoint is deprecated. Use /v2/users instead.'
  ),
  (req, res) => {
    res.json(profile);
  }
);

paths:
  /users/{id}/profile:
    get:
      deprecated: true
      summary: Get user profile (DEPRECATED)
      description: |
        **DEPRECATED:** This endpoint is deprecated and will be removed on 2024-12-31.
        
        **Use instead:** GET /users/{id}
        
        **Migration guide:** https://docs.example.com/migration
      responses:
        '200':
          description: User profile

GET /users/{id}/profile (DEPRECATED)

⚠️ Deprecated
This endpoint is deprecated and will be removed on 2024-12-31.
Use GET /users/{id} instead.

type User {
  id: ID!
  name: String! @deprecated(reason: "Use firstName and lastName instead")
  firstName: String!
  lastName: String!
}

{
  user(id: "123") {
    id
    name  # Warning: Field 'name' is deprecated. Use firstName and lastName instead.
  }
}

/**
 * @deprecated Use getUser() instead. Will be removed in v2.0.0.
 */
@Deprecated
public User getUserProfile(String id) {
    return getUser(id);
}

/**
 * @deprecated Use getUser() instead. Will be removed in v2.0.0.
 * @see getUser
 */
function getUserProfile(id) {
  console.warn('getUserProfile is deprecated');
  return getUser(id);
}

import warnings

def get_user_profile(id):
    warnings.warn(
        "get_user_profile is deprecated. Use get_user() instead.",
        DeprecationWarning,
        stacklevel=2
    )
    return get_user(id)

Banner:
⚠️ You're using a deprecated API endpoint (/users/:id/profile).
It will stop working on Dec 31, 2024.
[Migrate Now] [Learn More]

Status: Scheduled Maintenance

API v1 Sunset
Date: December 31, 2024
Impact: API v1 endpoints will stop working
Action: Migrate to API v2
Guide: https://docs.example.com/migration

# Release Notes - v1.5.0

## Deprecations
- GET /users/:id/profile (sunset: 2024-12-31)
  - Use: GET /users/:id
  - Guide: https://docs.example.com/migration

## Why We're Deprecating /users/:id/profile

We're consolidating user endpoints to:
1. Simplify our API (fewer endpoints to learn)
2. Improve performance (single endpoint, less overhead)
3. Provide more data (new endpoint returns additional fields)

## What to Use Instead

Use `GET /users/:id` instead of `GET /users/:id/profile`.

The new endpoint returns all profile data plus additional fields.

## How to Migrate

### Step 1: Update API Call

**Before:**
```javascript
const profile = await fetch('/api/users/123/profile');

const user = await fetch('/api/users/123');

const { bio, avatar, location } = profile;

const { bio, avatar, location } = user;
// Same fields, no changes needed

### Code Examples (Before/After)

See above

### Timeline (When It Stops Working)

**Example:**
```markdown
## Timeline

- **June 1, 2024:** Deprecation announced
- **September 1, 2024:** Reminder email
- **December 1, 2024:** Final warning
- **December 31, 2024:** Endpoint stops working (410 Gone)

## Need Help?

- **Email:** api@example.com
- **Office Hours:** Fridays 2-3pm PT (https://meet.google.com/xxx)
- **Slack:** #api-support
- **Schedule Call:** https://calendly.com/api-team

SELECT
  client_id,
  COUNT(*) as call_count
FROM api_logs
WHERE endpoint = '/users/:id/profile'
  AND date >= CURRENT_DATE - INTERVAL '7 days'
GROUP BY client_id
ORDER BY call_count DESC
LIMIT 10;

Calls/Day to /users/:id/profile

5000 |     ●
4000 |   ●
3000 | ●
2000 |       ●
1000 |         ●
   0 |___________●___
     Jun Jul Aug Sep Oct Nov

Trend: ↓ Declining (good!)

Alert: Deprecated endpoint usage spike
Endpoint: /users/:id/profile
Current: 5,000 calls/day
Previous: 1,000 calls/day
Change: +400%

Action: Investigate (new client using deprecated endpoint?)

Need help migrating?

We offer:
- 1-on-1 migration support calls
- Code review of your migration
- Extended sunset date (if needed)

Schedule a call: https://calendly.com/api-team

1. Identify major customers (high usage)
2. Email to schedule call
3. Call: Explain deprecation, offer help
4. Follow up: Check migration progress

Early Access: API v2

As a valued customer, we're offering early access to API v2.

Benefits:
- Test v2 before v1 sunset
- Provide feedback
- Smooth migration

Sign up: https://example.com/v2-early-access

Month 0: Initial announcement
Month 3: Reminder email
Month 6: Second reminder
Month 9: Final warning
Month 11: Last chance email
Month 12: Sunset

1. Email from API team (no response)
2. Email from account manager
3. Phone call from account manager
4. Executive escalation (if major customer)

Subject: URGENT: Action Required - API v1 Sunset in 30 Days

Hi [Client],

This is a final warning that API v1 will stop working in 30 days (December 31, 2024).

We noticed you're still using:
- GET /users/:id/profile (500 calls/day)

Action required:
- Migrate to GET /users/:id immediately
- See migration guide: https://docs.example.com/migration

If you don't migrate, your integration will break on December 31.

Need help? Reply to this email ASAP.

Thank you,
API Team

1. Sunset date reached
2. Return 410 Gone
3. Monitor for errors
4. Reach out to affected users

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "Endpoint Removed",
  "message": "GET /users/:id/profile was removed on 2024-12-31",
  "sunsetDate": "2024-12-31",
  "replacement": {
    "endpoint": "GET /users/:id",
    "documentation": "https://docs.example.com/api/users"
  },
  "migrationGuide": "https://docs.example.com/migration/profile-to-user",
  "support": "api@example.com"
}

1. Disable endpoint for 1 hour
2. Monitor errors
3. Identify affected users
4. Reach out
5. Re-enable
6. Give more time to migrate

2024-06: Launch v2
2024-06: Deprecate v1 (12 month notice)
2025-06: Sunset v1

v2: Active development
v1: Maintenance mode (bug fixes only, no new features)

1. Sunset v1 (stop working)
2. Monitor for 1 month
3. Remove v1 code
4. Celebrate! 🎉

-- Stop writing to 'name' column
-- Write to 'full_name' instead

-- Stop reading from 'name' column
-- Read from 'full_name' instead

-- After all code migrated
ALTER TABLE users DROP COLUMN name;

if (featureFlags.isEnabled('old-feature')) {
  console.warn('old-feature flag is deprecated. Will be removed in v2.0.0.');
  // Old feature code
}

Feature Flag: old-feature
Status: Deprecated
Sunset: 2024-12-31

Usage:
- Enabled for 10 users (down from 100)
- Last enabled: 2024-11-15

Subject: Feature Flag Deprecation: old-feature

Hi,

We noticed you have the 'old-feature' flag enabled.

This feature is deprecated and will be removed on 2024-12-31.

Action: Disable 'old-feature' flag and use 'new-feature' instead.

Need help? Reply to this email.

1. Sunset date reached
2. Force disable flag for all users
3. Monitor for errors
4. Remove feature code

// Remove old feature code
// Remove feature flag

deprecated: true
description: Migration guide

@deprecated(reason: "Use X instead")

Active → Deprecated → Sunset → Removed
Month 0:  Fully supported
Month 3: Deprecated (6-12 months notice)
Month 6: Final warning
Month 12: Sunset (stops working)

Jan 2024: API v1 active
Jun 2024: API v1 deprecated (announce v2)
Dec 2024: API v1 sunset (stops working)
Jan 2025: API v1 code removed

Deploy new version
→ All clients break immediately
→ Emergency rollback
→ Coordinate with all clients to update
→ Big bang migration (risky!)

Deploy new version
→ Old clients continue working
→ Clients migrate gradually
→ No coordination needed

### 3. Smooth Migration

**Gradual Migration:**

### 4. Reduce Coordination Overhead

**Without:**
- Coordinate deployment with all clients
- Schedule maintenance window
- Rollback plan if issues

**With:**
- Deploy anytime
- Clients migrate when ready
- No coordination needed

Month 0: Announce deprecation
Month 3: Reminder + usage stats
Month 6: Final warning
Month 12: Sunset

/**
 * @deprecated Use getUser() instead. Will be removed in v2.0.0.
 * @see getUser
 */
function getUserProfile(id) {
  console.warn('getUserProfile is deprecated. Use getUser() instead.');
  return getUser(id);
}

import warnings

def get_user_profile(id):
    """
    .. deprecated:: 1.5.0
       Use :func:`get_user` instead.
    """
    warnings.warn(
        "get_user_profile is deprecated. Use get_user() instead.",
        DeprecationWarning,
        stacklevel=2
    )
    return get_user(id)

## GET /users/:id/profile

**⚠️ DEPRECATED:** This endpoint is deprecated and will be removed on December 31, 2024.

**Use instead:** `GET /users/:id`

**Migration guide:** https://docs.example.com/migration

Subject: Deprecation Notice: /users/:id/profile endpoint

Hi developers,

We're deprecating the `/users/:id/profile` endpoint.

What's changing:
- Endpoint: GET /users/:id/profile
- Sunset date: December 31, 2024

Why:
- Consolidating user endpoints for simplicity
- New endpoint provides more data

Action required:
- Update your integration by December 31, 2024
- See migration guide: https://docs.example.com/migration

Need help?
- Reply to this email
- Schedule a call: https://calendly.com/api-team

Thank you,
API Team

# Deprecation Notice: /users/:id/profile Endpoint

**Date:** June 1, 2024

**Sunset Date:** December 31, 2024

We're deprecating the `/users/:id/profile` endpoint in favor of the consolidated `/users/:id` endpoint.

What's Changing
The `/users/:id/profile` endpoint will stop working on December 31, 2024.

Why
Consolidating user endpoints to simplify our API and provide a better developer experience.
The new endpoint returns all profile data plus additional fields.

Migration Guide
See our [migration guide](https://docs.example.com/migration) for step-by-step instructions.

app.get('/users/:id/profile', (req, res) => {
  // Track usage
  metrics.increment('deprecated.users_profile.calls', {
    client: req.headers['user-agent'],
    clientId: req.user?.clientId
  });

  // Return response with deprecation headers
  res.set('Deprecation', 'true');
  res.set('Sunset', 'Sat, 31 Dec 2024 23:59:59 GMT');
  res.set('Link', '<https://docs.example.com/migration>; rel="deprecation"');
  res.set('Warning', '299 - "This endpoint is deprecated. Use /users/:id instead. See https://docs.example.com/migration"');
  res.json(profile);
});

Deprecated Endpoint: /users/:id/profile
Sunset Date: 2024-12-31 (6 months remaining)
Usage:
- Total calls/day: 1,000 (down from 5,000 last month)
- Top clients: mobile-app (500), web-app (300), partner-api (200)

HTTP/1.1 200 OK
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Link: <https://docs.example.com/migration>; rel="sunset"

HTTP/1.1 200 OK
Deprecation: true
Link: <https://docs.example.com/migration>; rel="deprecation"

HTTP/1.1 200 OK
Warning: 299 - "This endpoint is deprecated. Use /v2/users instead. See https://docs.example.com/migration"

Month 0: Announce deprecation
Month 3: Reminder + usage stats
Month 6: Final warning
Month 12: Sunset

paths:
  /users/{id}/profile:
    get:
      deprecated: true
      summary: Get user profile (DEPRECATED)
      description: |
        **DEPRECATED:** This endpoint is deprecated and will be removed on 2024-12-31.
        
        **Use instead:** GET /users/{id}

---

## GraphQL Deprecation

**@deprecated Directive:**
```graphql
type User {
  id: ID!
  name: String! @deprecated(reason: "Use firstName and lastName instead")
  firstName: String!
  lastName: String!
}

/**
 * @deprecated Use getUser() instead. Will be removed in v2.0.0.
 * @see getUser
 */
@Deprecated
public User getUserProfile(String id) {
    return getUser(id);
}

/**
 * @deprecated Use getUser() instead. Will be removed in v2.0.0.
 * @see getUser
 */
/**
 * @deprecated Use getUser() instead. Will be removed in v2.0.0.
 */
function getUserProfile(id) {
  console.warn('getUserProfile is deprecated. Use getUser() instead.');
  return getUser(id);
}

import warnings

def get_user_profile(id):
    """
    .. deprecated:: 1.5.0
       Use :func:`get_user` instead.
    """
    warnings.warn(
        "get_user_profile is deprecated. Use get_user() instead.",
        DeprecationWarning,
        stacklevel=2
    )
    return get_user(id)

Subject: Action Required: Migrate from /users/:id/profile

Hi [Client],

We noticed you're still using the deprecated /users/:id/profile endpoint (500 calls/day).

This endpoint will stop working on December 31, 2024 (3 months remaining).

Action required:
- Migrate to GET /users/:id immediately
- See migration guide: https://docs.example.com/migration

Need help?
- Reply to this email
- Schedule a call: https://calendly.com/api-team
- Schedule a call: https://calendly.com/api-team

Thank you,
API Team

1. Disable endpoint for 1 hour
2. Monitor errors
3. Identify affected users
4. Reach out
5. Re-enable
6. Give more time to migrate

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "This endpoint has been removed. Use /v2/users instead.",
  "migrationGuide": "https://docs.example.com/migration",
  "support": "api@example.com"
}

if (featureFlags.isEnabled('old-feature')) {
  console.warn('old-feature flag is deprecated. Will be removed in v2.0.0.');
}

-- Stop writing to 'name' column
-- Write to 'full_name' instead

-- Stop reading from 'name' column
-- Read from 'full_name' instead

-- After all code migrated
ALTER TABLE users DROP COLUMN name;

## How to Migrate

### What's Changing
The `/users/:id/profile` endpoint is deprecated. Use `/users/:id` instead.

### Why
We're consolidating user endpoints to simplify our API and provide a better developer experience.

### How to Migrate

### Before
```javascript
const profile = await fetch('/api/users/123/profile');

const user = await fetch('/api/users/123');

---

## Templates

### Deprecation Announcement (Email)

See "Step 2: Announce" section above

### Deprecation Announcement (Blog)

See "Step 2: Announce" section above

---

## Best Practices

### Communication
- [ ] Communicate changes early
- [ ] Provide migration guides
- [ ] Hold breaking change meetings
- [ ] Create data contracts with consumers
- [ ] Document breaking changes clearly
- [ ] Document breaking changes with dates
- [ ] Set appropriate notice period (6-12 months minimum)
- [ ] Monitor deprecated endpoint usage
- [ ] Track consumer adoption
- [ ] Reach out to active users
- [ ] Provide support during migration
- [ ] Send reminders at key milestones
- [ ]

### Documentation
- [ ] Document all breaking changes with dates
- [ ] Document breaking changes clearly
- [ ] Provide migration guides for consumers
- [ ] Document version compatibility
- [ ] Document migration timeline
- [ ] Document sunset dates
- [ ] Keep documentation in sync with code
- [ ] Use consistent deprecation headers
- [ ] Use appropriate deprecation headers
- [ ] Include migration guide links
- [ ] Document breaking changes in changelog
- [ ] Document examples in documentation
- [ ] Document breaking changes in API docs
- [ ] Document breaking changes in README
- [ ] Document breaking changes in Swagger UI
- [ ] Document breaking changes in ReDoc
- [ ]

### Migration
- [ ] Use zero-downtime migration pattern
- [ ] Use multi-step migrations for breaking changes
- [ ] Backfill data before removing old columns
- [ ] Test migrations in staging environment
- [ ] Provide rollback procedures
- [ ] Monitor migration progress
- [ ] Support consumers during migration
- [ ] Use feature flags for gradual rollout
- [ ] Maintain backward compatibility during migration
- [ ] Use canary deployments for testing
- [ ]

### Monitoring
- [ ] Track deprecated endpoint usage
- [ ] Monitor breaking change impacts
- [ ] Track consumer adoption of new schema
- [ ] Set up dashboards for API health
- [ ] Alert on high usage of deprecated endpoints
- [ ] Monitor migration success rates
- [ ] Track time to sunset
- [ ]

### Testing
- [ ] Test backward compatibility
- [ ] Test with production-like data
- [ ] Test migration scripts thoroughly
- [ ] Test graceful degradation scenarios
- [ ] Monitor test coverage
- [ ]

### Prevention
- [ ] Use data contracts for all shared data
- [ ] Enforce schema validation at source
- [ ] [ ] Implement CI/CD schema checks
- [ ]

### Version Control
- [ ] Use semantic versioning
- [ ] Tag all releases with version numbers
- [ ] Document version compatibility matrix
- [ ] Maintain backward compatibility
- [ ] Use @deprecated directive for breaking changes
- [ ]

### Legal Compliance
- [ ] Follow contract terms if applicable
- [ ] Provide minimum notice period
- [ ] Ensure migration support
- [ ] Document breaking changes clearly
- [ ] Provide migration guides
- [ ] Maintain deprecation records

### Checklist
- [ ] Define deprecation process
- [ ] Set appropriate notice period
- [ ] Document breaking changes clearly
- [ ] Provide migration guides
- [ ] Monitor deprecated endpoint usage
- [ ] Track consumer adoption
- [ ] Set up dashboards for API health
- [ ] Track migration success rates
- [ ] Test backward compatibility
- [ ] Test with production-like data
- [ ] Monitor test coverage
- [ ] Optimize deprecation headers
- [ ] Use feature flags for gradual rollout
- [ ] Use zero-downtime migrations
- [ ] Backfill data before removing old columns
- [ ] Test migrations in staging environment
- [ ] Have rollback procedures ready
- [ ] Monitor schema drift metrics
- [ ] Track breaking change impacts
- [ ] Track consumer adoption of new schema
- [ ] Set up change notifications
- [ ] Test with production-like data
- [ ] Monitor test coverage
- [ ] Optimize schema validation overhead
- [ ] Cache schema definitions
- [ ] Use efficient validation libraries
- [ ] Monitor schema performance impact
- [ ] Establish schema ownership
- [ ] Create schema review process
- [ ] Define schema lifecycle
- [ ] Plan schema deprecation strategy
- [ ] Set up incident response for violations
- [ ] Test schema validation logic
- [ ] Train team on deprecation best practices