api-changelog-versioning

Creates comprehensive API changelogs documenting breaking changes, deprecations, and migration strategies for API consumers. Use when managing API versions, communicating breaking changes, or creating upgrade guides.

⭐9stars🔀0forks📁View on GitHub🕐Updated Jan 1, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill streamlines the creation of professional API changelogs and versioning documentation. It helps developers and product teams effectively communicate breaking changes, deprecation timelines, and migration strategies, ensuring a seamless experience for API consumers while maintaining high standards for technical documentation.

Use Cases

  • Documenting major version releases (e.g., v2 to v3) by highlighting breaking changes and providing clear 'before and after' code snippets to minimize integration friction.
  • Establishing transparent deprecation schedules and support policies to inform users about maintenance windows and end-of-life (EOL) timelines for legacy endpoints.
  • Generating step-by-step migration guides that provide specific instructions on updating authentication methods, base URLs, and response parsing logic.
  • Standardizing changelog formats across multiple microservices to ensure consistent communication with external developers and internal stakeholders.
nameapi-changelog-versioning
descriptionCreates comprehensive API changelogs documenting breaking changes, deprecations, and migration strategies for API consumers. Use when managing API versions, communicating breaking changes, or creating upgrade guides.

API Changelog & Versioning

Document API changes with clear migration paths and deprecation timelines.

Changelog Structure

# API Changelog

## v3.0.0 (2025-01-15) - Breaking Changes

### Breaking Changes
- Response format now follows JSON:API specification
- Authentication switched from API tokens to JWT Bearer

### Migration Steps
1. Update base URL to `/api/v3`
2. Replace `Authorization: Token xxx` with `Authorization: Bearer xxx`
3. Update response parsing for new envelope format

## v2.5.0 (2024-12-01) - Features

### New Features
- Webhook support for order events
- Batch operations endpoint
- Field filtering via `?fields=` parameter

### Improvements
- 56% faster response times on /products
- Enhanced error messages with field-specific suggestions

Deprecation Schedule

Version Status Support Until
v3.x Current Full support
v2.x Maintenance 2025-06-01
v1.x EOL Unsupported

Version Support Policy

  • Current: Full support, new features
  • Maintenance: Bug fixes and security only
  • EOL: No support, remove from docs

Migration Guide Template

## Migrating from v2 to v3

### Before (v2)
```json
{ "user_name": "john" }

After (v3)

{ "data": { "type": "user", "attributes": { "name": "john" } } }

Steps

  1. Update SDK to v3.x
  2. Modify response handlers
  3. Test in staging environment
  4. Update production

## Best Practices

- Provide 3-6 months deprecation notice
- Include before/after code examples
- Mark breaking changes prominently
- Maintain backward compatibility when feasible
- Version via URL path (`/api/v1/`) for clarity