Looker API 版本控制

大多数应用都是使用某种形式的客户端 SDK 或 API 网址编写的。客户端 SDK 和 API 网址绑定到特定的 Looker API 版本。即使 Looker 对新的 API 版本做出更改，您的应用也将继续正常运行。在您选择升级客户端 SDK（或修改 API 网址）以使用新的 Looker API 版本之前，您的应用不会受其他 API 版本中变更的影响。

Looker 如何更改 API

Looker API 的架构旨在为 Looker API 端点提供稳定性，进而为应用提供稳定性。

随着我们向 Looker 添加更多特性和功能，我们还会更新 Looker REST API 以访问或管理这些新功能。对于每个 Looker 版本，我们都会向当前版本的 Looker API 添加新的 API 函数、参数和响应类型属性。在大多数情况下，向 API 添加内容并不是破坏性更改，因此我们可以保留 API 的现有版本，而不会影响在 API 上构建的任何现有应用代码。您现有的应用代码可能只是不知道后续 Looker 版本中出现的新函数、参数或功能。

对于破坏现有应用代码的 API 更改，我们会将这些破坏性更改捆绑到新的 API 版本中。这意味着旧的 API 版本将继续像以前一样工作，而新的 API 版本将随更改和更新一起运行。一个 Looker 实例中可以有多个 API 版本，因此您可以选择何时升级到新的 API 版本。为调用旧端点而构建的现有代码将继续调用旧端点。新代码应调用最新 API 版本级别中的新版端点。

严重的安全问题除外。如果我们发现与 API 的特定部分相关的严重安全问题，将会尽快采取一切必要措施来缓解该安全问题，这可能包括在提供合适的解决方案之前停用易受攻击的功能。

如果我们需要停用某项功能、函数或属性以获得更好的实现或解决方案，我们通常会让当前 API 保持原样，但将关联的 API 端点标记为“已弃用”，以表示您应该远离应用代码中的端点。

API 的重大更改和添加更改

重大更改是指删除或重命名 API 端点的现有工件。这可能包括：

  • 更改或删除参数名称或类型
  • 添加新的必需参数
  • 更改基准网址
  • 更改或删除响应中的现有属性

另一方面，您可以对稳定的端点进行累加更改。其中可能包括：

  • 新的可选参数
  • 响应中的新属性（我们不认为此破坏性，因为我们假设您的代码会忽略响应中未知属性，这是 REST API 社区中的常见做法）

如果稳定的 Looker API 端点需要进行重大更改，才能继续采用新的架构或功能，则更改通常会添加到新端点并捆绑到新的 API 版本中，以便现有 API 端点保持不变。

API 端点的标志

大多数 API 端点都被视为“稳定”的 API 端点，这意味着它们不会发生变化。除非在极端情况下（例如为了解决安全问题），否则 Looker 无法发布对稳定端点的重大更改。

其他 API 端点可能会被标记为“Beta 版”或“已弃用”：

  • Beta 版端点正在积极开发中，将来可能会发生变化。它们不会受到破坏性更改的保护。使用 Beta 版端点时，请考虑对 Looker API 的更改是否会特别干扰您的应用或开发周期。如果您计划使用 Beta 版端点，请参阅 Looker 的版本说明，以便及时了解任何变化。
  • 已弃用的端点是指仍受支持且目前仍可使用，但在未来版本中删除的端点。应更新使用已弃用端点的旧代码，以停止使用已弃用的端点。当未来版本的 Looker 取消对该端点的支持时，仍在使用该端点的任何代码都将中断。在大多数情况下，已弃用的端点将被改进的功能所取代。如果您发现应用使用的是已弃用的函数或属性，则建议您重构代码以尽快替换已弃用的元素。

Beta 版端点和已弃用端点在 API Explorer 和 4.0 API 参考文档中都有相应标记。未标记的端点会被视为稳定。

迁移到新的 API 版本

当您选择将客户端 SDK 或 API 网址升级到新的 API 版本时，需要检查您的应用代码，确认您是否依赖于新 API 版本中的变化。请务必执行以下操作：

  1. 在应用代码中搜索更新后的函数、值和属性名称。
  2. 验证您的应用代码是否支持类型更改（例如从整数更改为字符串）。
  3. 审核您的代码（请参阅下一部分）。

审核代码

对于某些语言，可以在构建时以编译错误的形式发现 API 中的破坏性更改：

  • 如果您的应用是使用经过编译的强类型语言编写的，那么在新 API 版本中，对参数或响应类型的结构更改应该很容易出现，因为此类更改与现有代码不一致，这应该很容易就能看到编译类型检查和编译器错误消息。
  • 如果您的应用是使用松散类型的动态语言（例如 JavaScript、Ruby 和 Python）编写的，可能更难找到应用中会受新 API 版本中破坏性更改影响的部分。这些类型的语言可能需要执行运行时单元测试，才能找出与类型更改相关的任何问题。

在所有情况下，最佳实践都是让单元测试执行您的应用代码，包括对 Looker API 的调用（而不是模拟调用）。