# API 版本策略

> Shoplazza Admin API 的版本策略：YYYY-MM 命名、发布节奏、可用版本、版本下线，以及迁移检查清单。

Shoplazza Admin API 采用版本化管理，以便在引入新功能或破坏性变更时不影响现有应用。本页说明版本如何命名、多久发布一次、去哪里查看可用版本，以及迁移时该做什么。

## 版本命名

每个 API 请求都必须在 URL 路径中包含版本号。版本号采用 `YYYY-MM` 格式：

```
https://{shopdomain}.myshoplaza.com/openapi/{version}/{endpoint}
```

例如，以下 URL 调用 `2025-06` 版本：

```
https://{shopdomain}.myshoplaza.com/openapi/2025-06/articles
```

## 发布节奏

Shoplazza 每半年发布一个新的 API 版本。新版本可能新增接口和字段，或变更现有行为。旧版本在下线前会持续可用。

## 查看可用版本

要查看所有可调用的版本，打开 [API 参考](/zh-CN/api/openapi)，使用页面顶部的版本下拉菜单——它始终反映当前可用的版本。

## 版本下线（Sunset）

当你调用一个不再支持的版本时，请求将返回 `404` 状态码。请在版本下线前将应用切换到受支持的版本——在 [API 参考](/zh-CN/api/openapi) 的版本下拉菜单中确认当前可用的版本。

## 迁移检查清单

将应用迁移到新版本时：

1. 查看 [API 更新日志](/zh-CN/changelog)，确认新增、变更或移除的接口和字段。
2. 在测试店铺中针对新版本测试你的集成。
3. 更新请求 URL 中的版本段——例如把 `2025-06` 改为新版本。
4. 灰度切换，在将全部流量切到新版本前先监控错误。