Back to Details

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

API Changelog

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

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

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

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
  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

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

New 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

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

废弃计划

VersionStatusSupport Until
v3.xCurrentFull support
v2.xMaintenance2025-06-01
v1.xEOLUnsupported
版本状态支持截止日期
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

Migrating from v2 to v3

Before (v2)

Before (v2)

json
{ "user_name": "john" }
json
{ "user_name": "john" }

After (v3)

After (v3)

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

Steps

Steps

  1. Update SDK to v3.x
  2. Modify response handlers
  3. Test in staging environment
  4. Update production
undefined
  1. Update SDK to v3.x
  2. Modify response handlers
  3. Test in staging environment
  4. 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/
    ）以提升清晰度