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 端点都被视为稳定，这意味着它们不会发生变化。除非在极端情况下（例如为了解决安全问题），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（而不是模拟调用）。