---
name: API Changelog & Versioning
slug: api-changelog-versioning
category: Writing
description: API Changelog & Versioning creates changelogs that document breaking changes, deprecations, and migration steps for API consumers. Use it when releasing new API versions or planning upgrades.
github: "https://github.com/secondsky/claude-skills/tree/main/plugins/api-changelog-versioning/skills/api-changelog-versioning"
language: TypeScript
stars: 214
forks: 31
install: "npx degit https://github.com/secondsky/claude-skills/tree/main/plugins/api-changelog-versioning/skills/api-changelog-versioning ~/.claude/skills/api-changelog-versioning"
installs_to: ~/.claude/skills/api-changelog-versioning
source_path: plugins/api-changelog-versioning/skills/api-changelog-versioning/SKILL.md
collection_size: 24
category_size: 1144
collection_url: "https://dirskills.com/collections/secondsky/claude-skills"
added: 2026-09-04T05:25:52.991Z
last_synced: 2026-09-04T05:25:52.991Z
canonical_url: "https://dirskills.com/skills/api-changelog-versioning"
---

# API Changelog & Versioning

API Changelog & Versioning creates changelogs that document breaking changes, deprecations, and migration steps for API consumers. Use it when releasing new API versions or planning upgrades.

**Install:**

```bash
npx degit https://github.com/secondsky/claude-skills/tree/main/plugins/api-changelog-versioning/skills/api-changelog-versioning ~/.claude/skills/api-changelog-versioning
```

## README

# API Changelog & Versioning

Document API changes with clear migration paths and deprecation timelines.

## Changelog Structure

```markdown
# 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

```markdown
## Migrating from v2 to v3

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

### After (v3)
```json
{ "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