API Reference

版本管理

Smile API 版本管理指南

介绍

欢迎阅读 Smile API 版本管理指南。本文件概述了 Smile API 的版本控制策略和生命周期政策，帮助开发者顺利地集成我们的平台，同时有效地适应变化。

语义版本控制和发布阶段

Smile API 使用专注于主版本号的语义版本控制模式，结合不同的发布阶段。每个 API 版本可能会经历以下三个阶段：

  • Alpha
  • Beta
  • 正式发布（GA，General Availability）

版本编号格式

API 版本仅使用主版本号指定，遵循以下 URL 模式：

/v{major}/{phase}
  • 对于 Alpha 和 Beta 阶段，在 URL 中包含 {phase}。
  • 对于 正式发布 阶段，省略 {phase} 段。

示例：

  • Alpha 版本：/v1/alpha
  • Beta 版本：/v1/beta
  • 正式发布版本：/v1

版本生命周期和演进

阶段概述

Alpha 阶段（可选）

  • 目的： 与特定客户进行邀请制测试。
  • 访问权限： 不公开提供。
  • 用途： 收集新功能的反馈。

Beta 阶段（可选）

  • 目的： 在 Alpha 验证后为所有客户提供早期访问。
  • 访问权限： 公开提供给所有开发者。
  • 用途： 通过更广泛的反馈完善功能。

正式发布阶段

  • 目的： 官方稳定版供生产环境使用。
  • 访问权限： 公开提供，推荐所有集成使用。
  • 用途： 提供可靠的操作，在主版本内保持向后兼容性。

阶段间的转换

  • Alpha 到 Beta： 可能根据反馈包含重大更改。
  • Beta 到正式发布： 可能包含重大更改；目标是稳定性。
  • 跳过阶段： 某些 API 版本可能直接进入 Beta 或正式发布，省略早期阶段。

注意： 阶段之间的转换预计会有重大更改。

重大和非重大更改

为了维护稳定性，Smile API 区分了重大更改和非重大（增量）更改。

重大更改

重大更改可能会中断现有的集成。这些更改仅会在新的主版本 API 中引入。

重大更改的示例：

  • 移除整个操作（端点）。
  • 移除或重命名参数。
  • 移除或重命名响应字段。
  • 添加新的必需参数。
  • 将之前的可选参数改为必需参数。
  • 更改参数或响应字段的类型。
  • 移除枚举值。
  • 向现有参数添加新的验证规则。
  • 更改身份验证或授权要求。

非重大（增量）更改

非重大更改在不影响现有集成的情况下增强 API。这些更改将在同一主版本的所有受支持 API 版本中提供。

非重大更改的示例：

  • 添加新的操作（端点）。
  • 添加新的可选参数。
  • 添加可选的请求头。
  • 添加响应字段。
  • 添加响应头。
  • 添加枚举值。

API 版本支持政策

为了为迁移和开发提供充足的时间，Smile API 根据以下时间表支持每个版本：

阶段支持期限建议
Alpha在 Beta 发布后支持 6 个月不适用于生产环境；用于测试和反馈
Beta在正式发布后支持 12 个月适合早期采用者；建议迁移到正式发布版本
正式发布在下一个正式发布 API 版本发布后支持 24 个月推荐用于所有生产环境的集成

示例时间线：

  • v1 Alpha： 于 2022 年 1 月发布
  • v1 Beta： 于 2022 年 4 月发布
    • v1 Alpha 支持截至 2022 年 10 月
  • v1 正式发布： 于 2022 年 7 月发布
    • v1 Beta 支持截至 2023 年 7 月
  • v2 正式发布： 于 2024 年 1 月发布
    • v1 正式发布 支持截至 2026 年 1 月

在请求中指定 API 版本

在您的 API 请求中，包括主版本号和（如果适用）阶段来指定 API 版本。

URL 格式：

https://open.smileapi.io/v{major}/{phase}/...
  • 对于 正式发布 版本，省略 {phase}。

示例：

  • Alpha 版本（v1）：

    https://open.smileapi.io/v1/alpha/resource

  • Beta 版本（v1）：

    https://open.smileapi.io/v1/beta/resource

  • 正式发布版本（v1）：

    https://open.smileapi.io/v1/resource

迁移指南

为了确保与 Smile API 的无缝集成，在不同的 API 版本之间迁移时，请遵循以下指南：

迁移前

  • 查看文档： 阅读发行说明和更新的 API 文档。
  • 识别重大更改： 注意新版本中列出的任何重大更改。
  • 规划更新： 分配资源更新和测试您的集成。

迁移期间

  • 使用 Beta 版本进行测试： 利用 Beta 阶段测试您的集成并提供反馈。
  • 逐步实施： 从非关键组件开始，逐步更新您的代码库。
  • 维护向后兼容性： 如果可能，在过渡期间同时支持旧的和新的 API 版本。

迁移后

  • 监控性能： 注意日志和分析，尽早发现任何问题。
  • 提供反馈： 与 Smile API 团队分享您的经验，帮助改进未来版本。
  • 弃用旧的集成： 一旦确认无误，移除对已弃用 API 版本的支持。