API版本控制说明
Last updated
Last updated
Mshop 平台由于迭代开发速度快，将持续提供多个 API 版本。为确保您及时了解即将生效的 API 变更，我们建议您密切关注API发行日志。
如果需要升级应用的 API 版本，请参考详细的升级指导，以确保您的应用保持兼容并享受最新功能和优化。
Mshop 每 6个月发布一个新 API 版本。版本名称基于日期，以年-月形式进行定义，例如 2021-08。
平台支持多个 API 版本，您可以通过替换 URL 中的版本名称来指定所需的版本。API 版本分为三类：开发版本、最新稳定版本和最旧稳定版本。
每个稳定版本至少支持 12 个月，这意味着两个连续稳定版本之间至少有 6 个月的重叠期。当新稳定版本发布并包含对您应用有影响的更改时，您将有 6 个月的缓冲期来进行测试和迁移，之后旧版本将停止支持。
开发版本 (Unstable)：该版本用于发布新需求和技术改进的接口变更。开发版本允许您提前了解未来的稳定版本，帮助您尽早准备应用更新。开发版本与最新稳定版本在同一天发布。
最新稳定版本（Latest Stable) ：适用于生产环境，支持至少 12 个月。开发版本经过 6 个月的稳定期后，便会成为最新稳定版本。在该版本中，接口不会进行破坏性更改，确保您能够安全调用 API 而无需担心接口变更带来的影响。
最旧稳定版本（Oldest Stable）：适用于生产环境，支持至少 12 个月。每当有新版本发布时，最新稳定版本将转为最旧稳定版本，该版本中的接口也不会进行更改。
根据上述规则，您可以通过版本号或发布时间轻松了解 API 版本的状态。例如，版本 2024-10 将稳定支持至 2025年10月，随后才会被弃用。这种明确的时间框架帮助您提前规划应用的更新和迁移，确保其在新版本发布后的平稳运行。
发布版本
发布时间
版本支持日期截止时间
备注
2021-08
2021年08月01日
2024年04月01日
调用此版本自动滚动至最旧稳定版本
2023-10
2023年10月01日
2025年04月01日
最旧稳定版本
2024-10
2024年10月01日
2025 年 10 月01 日
最新稳定版本
2025-04
2024年10月01日
2026年04月01日
开发版本
如果您的应用程序调用了一个不曾受支持的版本，API 请求将返回 404 状态，例如调用2020-08版本时会出现这种情况。
如果您的应用程序调用了已废弃的版本，我们会将您的 API 请求自动转到最旧稳定版本。例如，当 Mshop 废弃 2021-08 版本时，针对 2021-08 版本的 API 请求将由 2023-10 版本来处理。这一机制确保应用在版本废弃后仍能继续运行，但我们建议尽快更新至最新稳定版本，以获得最佳支持和性能。
您可以为 Webhook 选择所需的 API 版本，该版本将用于发送到您应用的所有 Webhook 请求。当您选择的 API 版本不再受支持时，Mshop 会自动使用最旧稳定版本来支持您的 Webhook。
Webhook 请求中包含 X-Hotishop-API-Version 请求头，该请求头指示生成 Webhook 时使用的 API 版本。如果此值与您选择的版本不符，说明您所选择的 API 版本已不再受支持。
为避免 Webhook 版本变更对您的应用造成影响，请在更新应用 API 版本的同时，及时同步更新 Webhook 的 API 版本，确保您的应用与 Webhook 版本保持一致，减少兼容性问题和潜在的功能中断。
