api-changelog-versioning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Changelog & Versioning

API变更日志与版本管理

Document API changes with clear migration paths and deprecation timelines.

记录API变更，附带清晰的迁移路径和废弃时间线。

Changelog Structure

变更日志结构

markdown

undefined

markdown

undefined

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

Response format now follows JSON:API specification
Authentication switched from API tokens to JWT Bearer

Migration Steps

Update base URL to
```
/api/v3
```

Replace

Authorization: Token xxx

with

Authorization: Bearer xxx

Update response parsing for new envelope format

Update base URL to
```
/api/v3
```

Replace

Authorization: Token xxx

with

Authorization: Bearer xxx

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

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

undefined

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

undefined

Deprecation Schedule

废弃计划

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

版本	状态	支持截止日期
v3.x	当前版本	全量支持
v2.x	维护中	2025-06-01
v1.x	生命周期结束	不再支持

Version Support Policy

版本支持政策

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

当前版本：全量支持，新增功能
维护中：仅修复漏洞和安全问题
生命周期结束：无支持，从文档中移除

Migration Guide Template

迁移指南模板

markdown

undefined

markdown

undefined

Migrating from v2 to v3

Before (v2)

json

{ "user_name": "john" }

json

{ "user_name": "john" }

After (v3)

json

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

json

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

Steps

Update SDK to v3.x
Modify response handlers
Test in staging environment
Update production

undefined

Update SDK to v3.x
Modify response handlers
Test in staging environment
Update production

undefined

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

提前3-6个月发出废弃通知
包含变更前后的代码示例
显著标记破坏性变更
可行情况下保持向后兼容性
通过URL路径进行版本标注（
```
/api/v1/
```
）以提升清晰度