# SAP API Deprecation Policy

**Source**: [https://github.com/SAP-docs/api-style-guide/blob/main/docs/api-deprecation-policy-65a10e3.md](https://github.com/SAP-docs/api-style-guide/blob/main/docs/api-deprecation-policy-65a10e3.md)
**Last Verified**: 2025-11-21

**Attribution**: Content derived from [SAP API Style Guide](https://github.com/SAP-docs/api-style-guide) (Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/))

**Changes**: Consolidated from multiple source files, reorganized for progressive disclosure, added examples and templates.

---

## Table of Contents

1. [Overview](#overview)
2. [API Lifecycle States](#api-lifecycle-states)
3. [Timeline Requirements](#timeline-requirements)
4. [Required Metadata](#required-metadata)
5. [Stakeholder Responsibilities](#stakeholder-responsibilities)
6. [Deprecation Process](#deprecation-process)
7. [Decommission Process](#decommission-process)
8. [Best Practices](#best-practices)
9. [Examples](#examples)

---

## Overview

### Core Definition

A **deprecated API** "is no longer supported in future releases, and therefore not encouraged for use."

A **decommissioned API** has been fully retired and cannot be used in production.

### Key Principles

1. **Transparency**: Clearly communicate API lifecycle state to consumers
2. **Predictability**: Provide adequate notice before decommissioning
3. **Support**: Maintain deprecated APIs for minimum periods
4. **Documentation**: Update all documentation to reflect current state
5. **Migration Guidance**: Provide clear paths to successor APIs

---

## API Lifecycle States

SAP APIs use the `x-sap-stateInfo` attribute to define four lifecycle states:

### 1. Beta

**Definition**: Pre-production testing phase

**Characteristics**:
- Available for testing and evaluation
- May have incompatible changes without notice
- Not recommended for production use
- No support guarantees

**Use Case**: Early adopters testing new functionality

**Metadata**:
```yaml
x-sap-stateInfo:
  state: beta
```

### 2. Active

**Definition**: Live production-ready APIs

**Characteristics**:
- Fully supported for production use
- Backward compatibility maintained
- Default status (can be omitted from metadata)
- Full support and SLAs apply

**Use Case**: Standard production API usage

**Metadata**:
```yaml
x-sap-stateInfo:
  state: active
```

Or simply omit the attribute (active is default).

### 3. Deprecated

**Definition**: Live but replaced by an active successor

**Characteristics**:
- Still functional and supported (temporarily)
- Not recommended for new implementations
- Requires migration to successor API
- Support period defined (minimum 12 months)
- Must include deprecation date and successor information

**Use Case**: Legacy APIs being phased out

**Metadata**:
```yaml
x-sap-stateInfo:
  state: deprecated
  deprecationDate: "2024-01-15"
  successorApi: "NewAPIName v2.0"
```

### 4. Decommissioned

**Definition**: Retired from production

**Characteristics**:
- No longer functional
- Cannot be used in any environment
- Removed from documentation
- No support available

**Use Case**: Fully retired APIs

**Implementation**: Remove from artifact or mark in changelog

---

## Timeline Requirements

### Minimum Support Period After Deprecation

**12 months minimum** support period after deprecation announcement

**Calculation**:
- Starts from deprecation announcement date
- Continues until decommission date
- Allows customers adequate migration time

**Example Timeline**:
```
Jan 15, 2024: API deprecated (announcement)
Jan 15, 2025: Earliest decommission date (12 months later)
```

### Minimum Total Lifespan

**24 months minimum** total lifespan in active or deprecated status before decommissioning

**Calculation**:
- Starts from initial active release
- Includes time in active state + time in deprecated state
- Ensures reasonable API stability

**Example Timeline**:
```
Jan 1, 2022: API released (active)
Jan 1, 2024: API deprecated (24 months active)
Jan 1, 2025: Earliest decommission (12 months deprecated)

Alternative:
Jan 1, 2022: API released (active)
Jun 1, 2022: API deprecated (6 months active)
Jun 1, 2024: Earliest decommission (18 months deprecated, 24 total)
```

### Best Practice Timeline

SAP recommends:
- **Active period**: 18-36 months before deprecation
- **Deprecation period**: 12-24 months before decommission
- **Total lifespan**: 30+ months for production APIs

---

## Required Metadata

### OpenAPI Specification

APIs must include `x-sap-stateInfo` object in the OpenAPI specification file:

```yaml
openapi: 3.0.0
info:
  title: Employee Management API
  version: 1.5.0
  x-sap-stateInfo:
    state: deprecated
    deprecationDate: "2024-01-15"
    successorApi: "Employee Management API v2.0"
```

**Required Fields for Deprecated APIs**:
- `state`: Must be "deprecated"
- `deprecationDate`: ISO 8601 date format (YYYY-MM-DD)
- `successorApi`: Name and version of replacement API

### Artifact.json

APIs must include changelog entries in `artifact.json`:

```json
{
  "changelog": [
    {
      "state": "deprecated",
      "date": "2024-01-15",
      "version": "1.5.0",
      "notes": "Deprecated in favor of Employee Management API v2.0. Migration guide available at [https://help.sap.com/migration-guide"](https://help.sap.com/migration-guide")
    },
    {
      "state": "active",
      "date": "2022-01-01",
      "version": "1.0.0",
      "notes": "Initial release"
    }
  ]
}
```

**Required Fields**:
- `state`: Current API state
- `date`: State change date (ISO 8601 format)
- `version`: API version at state change
- `notes`: Descriptive information about the change

---

## Stakeholder Responsibilities

### Product Owners

**Lifecycle Decisions**:
- Determine when to deprecate APIs
- Decide deprecation timelines
- Identify successor APIs
- Approve decommission schedules

**Metadata Configuration**:
- Ensure `x-sap-stateInfo` properly configured
- Maintain accurate `artifact.json` changelog
- Verify metadata consistency across systems

**Communication**:
- Announce deprecation through release notes
- Publish blog posts about major deprecations
- Notify affected customers directly
- Provide migration timelines

**Support Management**:
- Maintain support during deprecation period
- Allocate resources for customer migration assistance
- Track migration progress
- Coordinate decommission activities

### UA (User Assistance) Developers

**Documentation Updates**:
- Add deprecation notices to API documentation
- Update API reference pages with warnings
- Create prominent deprecation banners
- Link to successor API documentation

**Decommission Documentation**:
- Remove links to decommissioned APIs
- Archive old documentation appropriately
- Redirect old URLs to successor documentation
- Update navigation and search indices

**Source Code Tags**:
- Apply `@deprecated` tag in Javadoc/JSDoc comments
- Include deprecation reason and alternative
- Update inline documentation
- Add migration code examples

**Migration Guidance**:
- Create migration guides in release notes
- Document API differences
- Provide code migration examples
- Publish before-and-after comparisons

### Development Teams

**Code Maintenance**:
- Continue bug fixes during deprecation period
- Maintain security patches
- No new feature development
- Plan removal timeline

**Testing**:
- Maintain test coverage during deprecation
- Test successor API thoroughly
- Validate migration paths
- Monitor customer usage patterns

---

## Deprecation Process

### Step 1: Decision and Planning

1. **Assess API Usage**:
   - Review usage metrics and analytics
   - Identify affected customers
   - Estimate migration effort

2. **Define Successor**:
   - Identify replacement API
   - Document migration path
   - Create migration guide

3. **Set Timeline**:
   - Calculate minimum support period (12 months)
   - Verify total lifespan requirement (24 months)
   - Set deprecation and decommission dates

### Step 2: Update Metadata

1. **OpenAPI Specification**:
```yaml
x-sap-stateInfo:
  state: deprecated
  deprecationDate: "2024-01-15"
  successorApi: "NewAPI v2.0"
```

2. **Artifact.json**:
```json
{
  "changelog": [{
    "state": "deprecated",
    "date": "2024-01-15",
    "version": "1.5.0",
    "notes": "Deprecated. Use NewAPI v2.0. Migration guide: [https://..."](https://...")
  }]
}
```

3. **Source Code** (Java example):
```java
/**
 * Gets customer address.
 *
 * @deprecated As of version 1.5.0, replaced by
 *             {@link com.sap.newapi.Customer#getAddress()}
 *             Use the new API which provides enhanced address validation.
 */
@Deprecated
public Address getCustomerAddress() {
    // implementation
}
```

### Step 3: Documentation Updates

1. **API Reference**:
   - Add deprecation banner at top of page
   - Include deprecation date and successor
   - Link to migration guide

2. **Release Notes**:
   - Announce deprecation
   - Explain reason for deprecation
   - Provide migration timeline
   - Link to migration guide

3. **Migration Guide**:
   - Document API differences
   - Provide code examples
   - Explain migration steps
   - List breaking changes

### Step 4: Communication

1. **Announcement Channels**:
   - Release notes
   - Blog posts
   - Email to affected customers
   - In-app notifications (if applicable)

2. **Announcement Content**:
   - What is being deprecated
   - Why it's being deprecated
   - When it will be decommissioned
   - What to use instead
   - Where to find migration guidance

### Step 5: Support Period

1. **Maintain Support**:
   - Continue bug fixes
   - Provide security patches
   - Answer customer questions
   - Monitor migration progress

2. **Track Migration**:
   - Monitor API usage metrics
   - Identify customers still using deprecated API
   - Proactively contact stragglers
   - Offer migration assistance

---

## Decommission Process

### Prerequisites

Before decommissioning, verify:
- [ ] Minimum 12 months since deprecation announcement
- [ ] Minimum 24 months total lifespan
- [ ] All customers notified
- [ ] Migration guidance published
- [ ] Successor API available and stable
- [ ] Remaining usage is minimal

### Decommission Methods

#### Method 1: Remove Entire API Package

**For complete API removal**:

1. Delete artifact folder from repository
2. Commit and push changes
3. Republish to SAP API Business Hub (API will be removed)

**Example**:
```bash
# Remove the API directory
rm -rf apis/EmployeeManagement/1.0

# Commit removal
git add -A
git commit -m "Decommission EmployeeManagement API v1.0"
git push
```

#### Method 2: Remove Specific Endpoints

**For partial API removal**:

1. Edit `artifact.json`
2. Remove specific endpoint definitions
3. Update changelog with decommission notice
4. Commit and push changes

**Example** (`artifact.json`):
```json
{
  "changelog": [
    {
      "state": "decommissioned",
      "date": "2025-01-15",
      "version": "1.5.0",
      "notes": "Endpoint /legacy/customers decommissioned. Use /v2/customers instead."
    }
  ],
  "paths": {
    "/v2/customers": { ... }
    // Removed: "/legacy/customers"
  }
}
```

### Post-Decommission Actions

1. **Documentation Cleanup**:
   - Remove API from documentation site
   - Archive old documentation
   - Set up redirects to successor API
   - Update navigation menus

2. **URL Management**:
   - Configure HTTP 410 (Gone) responses for old endpoints
   - Include message pointing to successor API
   - Maintain redirects for reasonable period

3. **Communication**:
   - Publish decommission announcement
   - Send final notification to any remaining users
   - Update status pages

---

## Best Practices

### Planning

1. **Early Assessment**: Evaluate deprecation candidates during product planning
2. **Customer Impact**: Always consider customer migration effort
3. **Batch Deprecations**: Group related API deprecations together
4. **Version Strategy**: Use semantic versioning to signal breaking changes

### Communication

1. **Multiple Channels**: Announce through all available channels
2. **Advance Notice**: Provide notice well before minimum period
3. **Clear Messaging**: Explain what, why, when, and how
4. **Regular Reminders**: Send periodic reminders during deprecation period

### Documentation

1. **Prominent Warnings**: Make deprecation notices highly visible
2. **Complete Migration Guides**: Don't just say "use X instead" - explain how
3. **Code Examples**: Provide before/after code comparisons
4. **FAQs**: Answer common migration questions

### Technical

1. **Graceful Degradation**: Consider warning headers before hard removal
2. **Usage Tracking**: Monitor deprecated API usage
3. **Migration Tools**: Provide automated migration tools when feasible
4. **Backward Compatibility**: Maintain during deprecation period

---

## Examples

### Example 1: REST API Endpoint Deprecation

**OpenAPI Specification**:
```yaml
openapi: 3.0.0
info:
  title: Order Management API
  version: 2.1.0

paths:
  /orders/{orderId}:
    get:
      summary: Get order details
      deprecated: true
      description: |
        **DEPRECATED**: This endpoint is deprecated as of January 15, 2024.
        Use /v2/orders/{orderId} instead.

        This endpoint will be decommissioned on January 15, 2025.

        Migration guide: [https://help.sap.com/order-api-migration](https://help.sap.com/order-api-migration)
      x-sap-stateInfo:
        state: deprecated
        deprecationDate: "2024-01-15"
        successorApi: "/v2/orders/{orderId}"
      responses:
        '200':
          description: Order details (deprecated)
          headers:
            Warning:
              schema:
                type: string
              description: '299 - "Deprecated API. Use /v2/orders/{orderId}"'
```

### Example 2: Java Method Deprecation

```java
/**
 * Service for managing customer data.
 */
public class CustomerService {

    /**
     * Retrieves customer by ID.
     *
     * @param customerId the customer identifier
     * @return customer object
     * @throws NotFoundException if customer not found
     * @deprecated As of version 2.0.0 (deprecated January 15, 2024),
     *             replaced by {@link #getCustomerById(String)}
     *             The new method provides enhanced validation and
     *             supports additional customer types.
     *             This method will be removed in version 3.0.0
     *             (scheduled for January 15, 2025).
     *             Migration guide: [https://help.sap.com/customer-api-migration](https://help.sap.com/customer-api-migration)
     */
    @Deprecated(since = "2.0.0", forRemoval = true)
    public Customer getCustomer(int customerId) throws NotFoundException {
        // Legacy implementation
        return legacyCustomerRetrieval(customerId);
    }

    /**
     * Retrieves customer by ID with enhanced validation.
     *
     * @param customerId the customer identifier (supports all formats)
     * @return customer object
     * @throws NotFoundException if customer not found
     * @throws ValidationException if customerId format invalid
     * @since 2.0.0
     */
    public Customer getCustomerById(String customerId)
            throws NotFoundException, ValidationException {
        // New implementation
        return enhancedCustomerRetrieval(customerId);
    }
}
```

### Example 3: Complete API Deprecation Timeline

**Timeline**: Document Management API

```
2022-01-01: API v1.0.0 released (active)
├─ State: active
├─ Full support and SLAs
└─ Production-ready

2023-06-15: API v2.0.0 released
├─ Enhanced features
├─ Better performance
└─ v1.0.0 remains active

2024-01-15: API v1.0.0 deprecated
├─ State: deprecated
├─ Deprecation announcement published
├─ Migration guide released
├─ Support continues
└─ x-sap-stateInfo updated

2024-07-15: 6-month reminder
├─ Email to remaining v1.0.0 users
├─ 6 months until decommission
└─ Migration assistance offered

2024-10-15: 3-month reminder
├─ Final migration push
├─ Direct contact to high-usage customers
└─ Migration tools provided

2025-01-15: API v1.0.0 decommissioned
├─ State: decommissioned
├─ Endpoints return HTTP 410 Gone
├─ Documentation removed
├─ Redirects to v2.0.0 documentation
└─ Final announcement published

Total Timeline:
- Active period: 24 months (Jan 2022 - Jan 2024)
- Deprecated period: 12 months (Jan 2024 - Jan 2025)
- Total lifespan: 36 months ✓ (exceeds 24-month minimum)
- Support after deprecation: 12 months ✓ (meets minimum)
```

---

## Reference

### External Standards

- **OpenAPI Specification**: [https://spec.openapis.org/oas/latest.html](https://spec.openapis.org/oas/latest.html)
- **Semantic Versioning**: [https://semver.org/](https://semver.org/)
- **HTTP Status Codes**: [https://httpstatuses.com/](https://httpstatuses.com/)

### SAP Resources

- **SAP API Business Hub**: [https://api.sap.com/](https://api.sap.com/)
- **SAP Help Portal**: [https://help.sap.com/](https://help.sap.com/)

### Related Documentation

- API Naming Guidelines
- API Quality Checklist
- API Review Process
- Developer Guide Standards

---

**Document Version**: 1.0.0
**Last Updated**: 2025-11-21
**Maintainer**: SAP Skills Team | [https://github.com/secondsky/sap-skills](https://github.com/secondsky/sap-skills)