REST API 客户端编写指南

目录

OpenAPI 规范 (OAS)

Slurmrestd 符合 OpenAPI 3.0.2 。 生成的 OAS 可以在以下 URL 查看：

  • /openapi.json
  • /openapi.yaml
  • /openapi/v3

可以通过以下方式直接生成 OAS：

  • 仅使用编译的 slurmrestd 生成 OAS：
    env SLURM_CONF=/dev/null slurmrestd --generate-openapi-spec -s slurmctld,slurmdbd -d v0.0.40
  • 使用完全配置的 Slurm 安装生成 OAS：
    slurmrestd --generate-openapi-spec -s slurmctld,slurmdbd -d v0.0.40

OAS 旨在成为请求方法和响应的主要文档，包括其内容。有几个第三方工具可以自动生成与 OAS 输出相对应的文档，这些工具在openapi.tools中列出。 生成文档的示例在这里。

生成的 OpenAPI 规范会根据运行时 slurmrestd 的配置而变化。slurmrestd 是一个框架，实际内容由插件提供，这些插件在运行时是可选的。然而，特定插件版本（如路径中的 v0.0.XX 所示）将在 Slurm 版本之间保持稳定，只要相关插件仍然存在。插件生命周期在这里描述。

OpenAPI 标准合规性

Slurm 努力严格遵守相关的OpenAPI 标准。 出于兼容性原因，Slurm 的 OAS 会针对公开可用的 OpenAPI 客户端生成器进行测试，但 Slurm 并不直接支持任何这些生成器，因为它们超出了 SchedMD 的控制，可能随时更改。目标是遵循标准，支持尽可能多的客户端，而不偏向任何一个客户端。网站始终欢迎编写符合 OpenAPI 的客户端。一般来说，SchedMD 将调试发送到 slurmrestd 的 HTTP 请求和接收的响应，但不会直接调试任何客户端源代码。

测试的兼容性通过 OpenAPI 插件：

OpenAPI 规范 (OAS) 文档

Slurm 包含示例生成的文档，随每个版本提供。Slurm 的文档仅包含最新的插件，以鼓励网站针对最新插件进行开发，因为它们将具有最长的生命周期，因此新客户端将持续工作更长时间。插件生命周期在这里描述。此文档是通过以下步骤生成的，使用OpenAPI-generator HTML 输出：

  1. 生成 OAS：
    env SLURM_CONF=/dev/null slurmrestd --generate-openapi-spec -s slurmctld,slurmdbd -d v0.0.40 > openapi.json
  2. 生成文档：
    openapi-generator-cli generate -i openapi.json -g html -o rest_api_docs
  3. 将浏览器指向rest_api_docs/index.html

Swagger 提供了一个网络编辑器来查看和与生成的 OAS 进行交互。它使得通过Swagger Codegen生成客户端和文档相对简单。

客户端设计

客户端应始终针对或设计为与来自slurmrestd的特定版本的标记路径一起使用。强烈建议客户端开发者不要包含不打算使用的方法版本的功能。

如果计划支持多个版本，客户端开发者需要计划如何优雅地处理不同 Slurm 版本之间的更改。Slurm 的版本控制方法是明确的，以允许旧代码继续与较新的 Slurm 版本一起工作，同时仍然支持该旧版本。例如，v0.0.38 方法是在 Slurm-22.05 中添加的，但可以使用直到 Slurm-24.05。虽然这样做有效，但这些方法不会获得任何新特性或功能，通常只会有安全修复。Slurm 每个版本都会获得几个新特性，这些更改会通过新插件版本的更改反映出来。希望使用新特性的客户端将必须迁移到较新版本，因为新特性不会被回溯移植。

建议使用仅为一个版本生成的 OpenAPI 架构。许多 OpenAPI 客户端生成器都有一种方法可以从结构名称中去除版本标签（即V0039AccountFlagsDELETED -> AccountFlagsDELETED）。这可以允许创建一组未版本化的基础代码，然后根据输出代码与较新 Slurm 版本的实质性更改进行调整。使用强类型语言可以大大帮助这一点。通常，特定端点之间不同版本的架构仅有部分变化，尽管查看它们的差异可能会令人畏惧，即使使用像json-diff这样的工具。另一种选择是使用包装器来处理版本差异，就像许多 C 库处理 Windows 和 Linux 之间的差异一样。

生成的 OpenAPI 架构可能会变化，具体取决于存在的插件，但版本化路径及其架构不会变化（有限例外）。因此，生成一个仅限于v0.0.40的架构并将其放入您的代码库中，应该会产生一个可以在 Slurm-23.11 到 Slurm-25.05 中使用的架构。一般来说，重新生成客户端代码和 OpenAPI 架构将是适得其反的，因为即使是 OpenAPI 生成器本身也可能在其版本之间为相同的 OpenAPI 规范生成不同的结果。即使服务器没有发生任何变化，相同的驱动程序代码可能也不会编译。此类问题的具体示例可以在这里找到。

开发者可能希望考虑在客户端的代码库中拥有一组相对静态的编译客户端代码。然后，这些代码只需在标记版本内的修订中进行更新，这通常是非常少见的。这将消除最终用户运行代码生成器的需要，并限制任何更改干扰工作流程的机会。 这还将允许您在方便的时间进行升级，而不是必须确保多个排列的兼容性。

开发者应意识到，版本化插件的旧版本会按照文档化的节奏从 Slurm 中移除，如这里所示。 一旦相关插件版本被移除，客户端将需要升级以继续与 slurmrestd 通信。

如果 slurmrestd 编译成功，那么所有内容都将编译成功。然而，slurmrestd 和 slurm.conf 的运行时参数将更改 OAS 的输出。例如，如果未配置 slurmdbd 记账，则/slurmdb/路径将自动不包含，因为存在无效的前提条件。查询这些路径的客户端将收到 404 错误。slurmrestd 也可以并且应该被告知加载最少数量的插件（通过 -d 和 -s），这也会改变哪些路径存在，因此包含在 OAS 中。对于 slurmrestd，OAS 只是文档的一种形式，与其功能无关。客户端可以生成许多当前运行的 slurmrestd 没有加载的路径。该客户端只会对这些查询返回 404 错误，并应通过内部逻辑避免它们。客户端只需对其实际查询的路径/端点具有匹配的 OAS。由于 slurmrestd 中的所有端点都是版本化的，因此自动保证它们将正常工作（如果存在），就像客户端查询原始 slurmrestd 一样，该原始 slurmrestd 用于生成其编译的原始 OAS。如果同一版本的路径行为不一致，则这是一个错误，我们恳请您提交工单以便我们修复。

在非常有限的情况下，slurmrestd 将生成具有不同功能的相同端点的 OAS。

  • 如果规范在某种程度上根本性地损坏，以至于违反了 OpenAPI 标准。Slurm 有测试单元来尝试捕捉这一点，但这些测试并不完美。
  • 添加了新字段或路径。这不应破坏客户端，因为客户端应忽略 JSON/YAML 中的未知字段。

OpenAPI 规范 (OAS) 更改

OAS 的更改始终在每个版本中列出，详见OpenAPI 发布说明。

查看版本之间差异的一个简单技巧是查询两个版本，然后掩盖较新的版本，以避免 diff 列出每个更改的版本标签： 

env SLURM_CONF=/dev/null slurmrestd -d v0.0.41 -s slurmdbd,slurmctld --generate-openapi-spec > /tmp/v41.json
env SLURM_CONF=/dev/null slurmrestd -d v0.0.40 -s slurmdbd,slurmctld --generate-openapi-spec > /tmp/v40.json
cat /tmp/v41.json | sed -e 's#v0.0.41#v0.0.40#g' > /tmp/v41_masked.json
vimdiff /tmp/v40.json /tmp/v41_masked.json
jsondiff /tmp/v40.json /tmp/v41_masked.json

有时这个技巧仍然会在 diff 输出中产生太多变化而无法有用。在这些情况下，选择特定的（子）架构可能会有所帮助： 

jq '.components.schemas."v0.0.40_job"' /tmp/v40.json > /tmp/v40_job.json
jq '.components.schemas."v0.0.40_openapi_job_info_resp".properties.jobs.items' /tmp/v41_masked.json > /tmp/v41_masked_job.json
vimdiff /tmp/v40_job.json /tmp/v41_masked_job.json

生成的 OpenAPI 架构非常详细，并且随着每个版本的发布变得更加详细，因为我们添加了更多的枚举，更好地暴露可能的值并增加了注释中的文档。即使是树结构的微小变化也可能导致生成的架构中出现大量变化，这在查看差异时可能会令人困惑。上面的示例显示了v0.0.40_job被内联到v0.0.40_openapi_job_info_resp中。 根据生成的客户端，该更改可能根本不会改变结果客户端代码。

最后修改于 2025 年 6 月 5 日