API 版本管理说明​

为了应对不断发展的业务场景，SHOPLINE 会定期进行 OpenAPI 版本迭代，以此确保开发者能够构建能力丰富且贴近商家实际使用场景的应用能力，同时为开发者提供可预测的功能升级和弃用路径。 为确保你始终了解即将推出的 API 变更内容，请关注 SHOPLINE 开发者中心发出的站内信和邮件，并确保你的开发者联系人信息的有效性。

版本化和非版本化 API​

版本化 APIs

• Admin REST API
• Admin GraphQL API
• Storefront API
• Webhook

未版本化 APIs

• Ajax API
• Handlebars

调用 API 版本​

在调用 SHOPLINE API 的时候需要在请求URL中明确声明使用的接口版本：
REST Admin API URL： /admin/openapi/{version}/{endpoint}.json
Storefront API URL：/storefront/graph/{version}/graphql.json

例如在请求 v20230301 版本接口的时候，你应该这么请求：
REST Admin API URL： /admin/openapi/v20230301/order.json
Storefront API URL：/storefront/graph/v20230301/graphql.json

当一个接口在多个版本中被支持时，你可以通过在 URL 中替换版本名称来指定要使用的版本。

版本标识说明​

一般情况下，SHOPLINE OpenAPI 版本会以3个月一次的频率进行迭代升级。 SHOPLINE 透出的版本包括了 3 种类型：稳定版本、候选版本和不稳定版本

稳定版本​

• 稳定版本可以让你安全调用 API，而不用担心接口被更改。
• 通常我们一个版本转为稳定版本后会持续服务12个月。这意味着连续的两个版本会有9个月的重叠服务期，也就是当一个新的稳定版本引入了影响你的应用程序的变更时，你可以有9个月的时间进行迭代迁移。

候选版本​

• 候选版本可以理解为下一个稳定版本的预览版本。在这个版本中你可以看到下一个稳定版本计划发布的变更。
• 通常上一个版本稳定时，下一个版本就会转为候选版本。例如，当版本v20230901在变更为稳定版本时，v20231201将作为候选版本发布。
• 候选版本中的接口会包含所有向后兼容或向后不兼容的变更，你可以根据这个版本的变化，尽早开始更新你的应用，但不建议你在生产环境中直接使用候选版本。

不稳定版本​

• 不稳定的版本包含仍在开发和迭代中的接口和更新，我们会不定期对它们进行向后兼容或向后不兼容的更改。
• 一个特性被添加到不稳定的版本中后，仍然有可能被删除。你可以利用不稳定版本尽早测试新的接口和功能，但不建议在生产环境中使用它们。

废弃处理方式​

• 如果 SHOPLINE API 的一部分变得不必要、不安全或过时，平台有可能会弃用它。
• 当一个接口或资源在最新的版本中被删除时，它会被标记为已弃用；调用该 API 时将向前追溯到最近一个可用的稳定版本。当最后一个可用版本失效时，这个字段将无法继续使用。
• 有关新版本的重大变更，我们会在版本发布时以邮件和站内信形式通知到开发者，同时你也可以关注文档中心的版本变更日志。

发布时间表​