Workiva 的 API 版本控制
应用程序编程接口 (API) 版本控制是一项关键实践，它为 API 设计的不同迭代版本分配唯一标识符，以便有效地管理和沟通变更。它的主要目的是保持向后兼容性，确保依赖旧版本的脚本和应用程序在新 API 版本发布时不会出现故障。这种稳定性使得 API 提供商能够在不影响现有用户的情况下引入重大更新、错误修复和新功能，从而让消费者有时间和控制权在准备就绪时迁移他们的系统。归根结底，正确的 API 版本控制能够促进可靠、可扩展和专业的开发生态系统的形成。
2026-01-01 API 版本发布
Workiva 将于 2026 年 1 月发布新的 API 版本， 2026-01-01。新版本在多个方面进行了重大改进，包括提高一致性、增加新功能以及弃用旧功能。升级到 2026-01-01 版本的好处包括：继续兼容最新的 Workiva 平台功能、增强的安全性、改进的性能以及利用新功能的能力。
有关新 API 版本的更多信息，请参阅 Workiva API 2026-01-01 升级指南。
2022年1月1日API版本已弃用
随着 2026-01-01 版本的发布，较旧的 2022-01-01 版本将进入弃用阶段。对该旧版本的支持将持续到 2029 年 1 月终止，而对 2022-01-01 原型端点的支持将于 2027 年 1 月结束。
注： 2022 年 1 月 1 日版本中的大多数原型端点已在 2026 年 1 月 1 日版本中升级为正式版 (GA)。
| 版本 | 状态 | 端点类型 | 日落日期 |
|---|---|---|---|
| 2026-01-01 | 正式发布 (GA) | 全部 | 不适用（当前） |
| 2022-01-01 | 已过时 | 原型 | 2027年1月 |
| 2022-01-01 | 已过时 | GA | 2029年1月 |
比较 API 版本
当发布新版本时，Workiva Developers Hub 上该版本的 API 文档会包含一个变更日志部分，其中包含有关该版本 API 变更的详细文档。2026-01-01 版本将包含一个 2026-01-01 升级指南 部分，其中将完整介绍该版本中的更改。
此外，还有许多开源工具可用于对两个不同的 API 版本进行比较。这类工具可以快速、详细地比较版本变化。开源工具 oasdiff 有一个 基于 Web 的差异计算器 ，允许您上传两个 API 版本配置文件 (oas.yaml) 并运行比较，以查看重大更改、变更日志或原始差异。它可以将结果输出为文本、yaml、json、html 和 markdown 格式。
参考特定 API 版本
Workiva API 利用 X-Version 标头来指定要使用的 API 版本。如果没有传递 X-Version 标头，则版本默认为已弃用的 2022-01-01 版本。
注意： 2029 年 1 月之后，X-Version 标头将成为必需项，所有缺少此标头的 API 调用都将失败。
要通过 Python 在 API 请求中指定版本，请在每个 API 请求的标头中包含键/值对。例如： headers = {'X-Version': '2026-01-01'}
目前您可以指定 2026-01-01 或 2022-01-01。
由于 2026-01-01 版本有很多重大变更，因此必须确保 X-Version 标头已设置为适用的版本，并且 API 端点 URL 路径和参数与该版本所需的结构相匹配。此外，了解 API 调用的响应格式以及不同版本之间该格式的任何潜在差异也很重要。
实例
GET 请求示例
以下是 2026-01-01 和 2022-01-01 版本在“检索电子表格列表”端点中使用 GET 请求的示例（本文中，为了混淆目的，这些示例将 bearer token 作为 token 变量）。
2026-01-01 版本
# 2026-01-01 版本 # 注意 X-Version 标头和请求 URL 标头 = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2026-01-01', } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, )2022-01-01 版本
# 2022-01-01 版本 # 注意 X-Version 标头和请求 URL 标头 = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } resp = requests.get( 'https://api.app.wdesk.com/platform/v1/spreadsheets', headers = headers, ) PATCH 请求示例
下面是一个示例，展示了如何在 2026-01-01 和 2022-01-01 版本中，在“部分更新单个部分”端点中使用 PATCH 请求（为了混淆目的，本文中的这些示例将 bearer token 作为 token 变量）。
2026-01-01 版本
# 2026-01-01 版本 # 注意 X-Version 标头和请求 URL 标头 = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization':token, 'X-Version': '2026-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "我的新版块名称" } ] resp = requests.patch ( https://api.app.wdesk.com/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) 2022-01-01 版本
# 2022-01-01 版本 # 注意 X-Version 标头和请求 URL 标头 = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "我的新版块名称" } ] resp = requests.patch( f'https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) 提示： 除了确保URL路径和参数结构与适用的API版本匹配外，还务必查看文档以了解有关可用参数选项的详细信息。
例如，在上面的“部分更新单个部分”示例中，2022-01-01 版本有三个可用的路径选项（/name、/index、/parent），但在 2026-01-01 版本中有超过三十个可用的路径选项。
脚本编写和 API 版本控制的最佳实践
虽然您需要的具体 API 版本可能取决于活动脚本和应用程序的状态、升级到新 API 版本的时间表或其他因素，但以下是一些与脚本编写和 API 版本控制相关的最佳实践。
务必指定 API 版本
永远不要依赖 API 提供商的默认版本。每次 API 调用时都要明确指定版本。通过明确指定版本，您可以控制脚本或应用程序运行的版本。
集中管理版本常量
将 API 版本定义为脚本顶部或单独的配置文件中易于查找的单个常量或配置变量。这可以可靠地简化故障排除流程并提高可维护性。例子：
# 在 config.py 或主脚本顶部设置 API_VERSION = '2026-01-01' # 在 requests 调用中设置 headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': API_VERSION, } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, ) 避免混用不同版本的API。
请勿在单个脚本或应用程序中混用不同的 API 版本。单个脚本或应用程序中的所有 API 调用都应引用相同的 Workiva API 版本（例如，所有 API 调用都应使用“2026-01-01”版本）。混合使用不同版本会使调试、请求模式和响应格式变得复杂，导致脚本行为不可预测，维护也更加复杂。
隔离 API 交互逻辑
创建一个专用模块或一组函数（通常称为“包装器”或“客户端”），用于处理与外部 API 的所有通信。这种模式将脚本的“业务逻辑”与“API 通信逻辑”分开。如果 API 发生变化（例如，新 API 版本中的端点 URL 或请求/响应结构发生变化），则只需要更新包装函数，而无需更新整个脚本。
优雅地处理已弃用的端点和参数
从旧版 API 迁移到新版时，请预料到端点和参数可能会被重命名或删除。确保脚本包含强大的错误处理和日志记录功能，因为这有助于脚本开发的最佳实践，并提高捕获和记录版本相关错误的概率。
有关脚本编写最佳实践的更多信息，请参阅 Workiva 脚本编写：开发最佳实践 文章。
监控和规划折旧
Workiva 正在调整策略，每年发布两个主要新版本窗口：春季和秋季。如果临近发布日期时没有发生重大变更，并且该时期的发布候选版本为空，则 Workiva 届时不会发布新版本的 API。
我们建议您积极关注 Workiva API 开发者中心 网站，订阅 Workiva 发行说明，并遵循已发布的发行和弃用计划。使用已弃用 API 版本的脚本最终会失效。了解 API 版本的终止（生命周期结束）日期，可以让你在 终止日期之前安排必要的 升级工作。
脚本迁移和验证
为确保 API 版本无缝迁移，建立并行测试策略：复制现有的生产脚本，仅修改副本以针对新的 API 版本（包括对标头、URL 路径和/或请求/响应结构的任何必要更改），然后测试新旧脚本，以比较和验证功能和输出。
通过在受控环境中并排运行它们，您可以将稳定的旧脚本作为标准来监控和验证新脚本产生的功能和结果是否相同，然后再完全切换到新版本并弃用旧版本。