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 则会与其并行运行，并包含相应更改和更新。多个 API 版本可以在单个 Looker 实例中并存，以便您选择何时升级到新 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 的未来版本移除对该端点的支持时，仍在使用该端点的所有代码都会失效。在大多数情况下，已弃用的端点将被改进的功能所取代。如果您发现自己的应用使用的是已弃用的函数或属性，最好重构代码以尽快替换已弃用的元素。

API Explorer 和 4.0 API 参考文档中会将 Beta 版端点和已废弃的端点标记为 Beta 版和已废弃。未标记的端点被视为稳定。

迁移到新 API 版本

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

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

审核您的代码

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

  • 如果您的应用程序是使用编译的强类型语言编写的，那么，由于编译类型检查和编译器错误消息，在新的 API 版本中对参数或响应类型进行结构更改时，与现有代码不一致的情况应显而易见。
  • 如果您的应用是使用松散类型的动态语言（例如 JavaScript、Ruby 和 Python）编写的，则在新 API 版本中，找到受破坏更改影响的应用部分可能更加困难。这类语言可能需要运行时单元测试来查找与类型更改相关的任何问题。

在任何情况下，最佳做法都是让单元测试来测试您的应用代码，包括对 Looker API 的调用（而不是模拟调用）。