Category: Documentation
Description
Deprecated endpoints should explain the migration path or replacement to help API consumers transition away from deprecated functionality.
What It Checks
This rule examines operations marked as deprecated and analyzes their documentation:
- Checks the summary and description fields
- Uses AI to determine if adequate migration guidance is provided
- Looks for replacement endpoints, timelines, or explanations
Why It Matters
Clear deprecation guidance:
- Smooth Transitions: Users know how to migrate
- Reduced Support: Fewer questions about deprecated endpoints
- Professional API: Shows care for API consumers
- Clear Communication: Transparent about API evolution
Examples
Good
paths:
/users/legacy:
get:
deprecated: true
summary: Get users (deprecated)
description: |
This endpoint is deprecated and will be removed in v3.0.
Please use GET /v2/users instead, which provides the same
functionality with improved pagination support.
responses:
'200':
description: List of users
Bad
paths:
/users/legacy:
get:
deprecated: true
summary: Get users
# No description explaining the deprecation or migration path
responses:
'200':
description: List of users
Exceptions
- Internal APIs where deprecation is communicated through other channels
- Endpoints deprecated due to security issues (may not want to publicize details)
Configuration
This rule has no configuration options. It is either enabled or disabled.
Related Rules
- Rule 77: Semantic Consistency - API-wide consistency
- Rule 78: Tag Organization - API organization