使用 JSON Home 进行版本/扩展发现

bp json-home

Keystone 服务器通过响应 GET /、GET /v2.0 和 GET /v3 操作来提供版本发现。此响应的格式是 Keystone 特有的 JSON 文档（在 Identity API 规范中定义）。Keystone 应该支持 JSON Home，因为这是一种更标准的 REST API 发现方式。这将有助于标准化 OpenStack 生态系统中的版本发现。

这在 openstack-dev 邮件列表中讨论过。

问题描述

应用程序编写者需要与不同的 OpenStack 服务交互，因此她首先编写一些代码来与服务器通信，以发现每个服务器支持的 API 版本。她发现所有服务器都提供不同的响应，因此必须为每个服务编写自定义代码。这比应该更难，因为所有服务都应该使用相同的格式来表示其版本文档。为版本文档选择的格式应该提供一种基于链接的方法，例如 JSON Home。

通过此更改，Keystone 将提供一个 JSON Home 文档，使其与其他使用 JSON Home 的服务保持一致。

提议的变更

V3 Identity API 规范将被更改为记录服务器可以响应 GET /v3 请求并提供 JSON Home 文档，如果 Accept 头部是 application/json-home，并且提供响应示例。Identity API v2 的 WADL 将以类似的方式更新，请参见 Identity API v2。

Keystone 服务器将被更改为检查 GET /、GET /v2.0 和 GET /v3 请求上的 Accept 头部，如果头部指示 application/json-home 是优于 application/json 的首选格式，则服务器将生成 JSON Home 文档，而不是正常的 JSON 响应。

这是一个只包含 /v3/users 和 /v3/users/{user_id} 的最小文档示例

{
  "resources": {
    "https://docs.openstack.org/api/openstack-identity/3/rel/users": {
      "href": "/v3/users"
    },
    "https://docs.openstack.org/api/openstack-identity/3/rel/user": {
      "href-template": "/v3/users/{user_id}",
      "href-vars": {
        "user_id": "https://docs.openstack.org/api/openstack-identity/3/param/user_id"
      },
    },
    // ...
  }
}

resources 属性的键是链接关系类型。需要为键选择一种关系类型。有几种关系类型 在 IANA 注册，但没有指定用于 Identity API 资源的类型。如果一个组不想在 IANA 注册关系（请参阅 RFC 5988 的第 4.2 节“扩展关系类型”），他们可以使用一些唯一的 URL 代替。应用程序可能会获取此 URL 以获取有关关系的更多信息，因此我们应该选择一个可能用于提供有关关系信息并描述资源的 URL。Nova 项目在其 XSD 文件中发布其文件：https://docs.openstack.org/api/openstack-compute/2/xsd/，因此 Keystone 应该在其类似位置发布其文件，以保持一致性。对于 v3 资源，关系类型链接将类似于 https://docs.openstack.org/api/openstack-identity/3/rel/<type>，其中 <type> 类似于 users、user、projects 等。

参数的关系 URL 也需要选择。对于 v3 参数，它们将类似于 https://docs.openstack.org/api/openstack-identity/3/param/<parameter-type>，其中 <parameter-type> 类似于 user_id、project_id 等。

服务器返回的 JSON Home 文档将根据启用的扩展而变化。在管道中的已启用扩展将拦截 GET 请求并更新响应。

对于 v3 API（对于 V3）、已启用的 V3 扩展、公共和管理 v2 API 以及已启用的 v2 扩展中的每个资源模板，resources 中将有一个资源。

这是一个扩展 OS-EP-FILTER 的资源示例

{
  "resources": {
    "https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/project_endpoint": {
      "href": "/v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id}",
      "href-vars": {
        "project_id": "https://docs.openstack.org/api/openstack-identity/3/param/project_id",
        "endpoint_id": "https://docs.openstack.org/api/openstack-identity/3/param/endpoint_id"
      }
    }
  }
}

扩展的关系类型将类似于 https://docs.openstack.org/api/openstack-identity/<api-version>/ext/<extension-name>/<extension-version>/rel/<resource>。

扩展使用的参数的关系类型将类似于 https://docs.openstack.org/api/openstack-identity/<api-version>/ext/<extension-name>/<extension-version>/param/<param-id>。

Keystone 提供的扩展具有实现 keystone.common.wsgi.ExtensionRouter 类的路由器。将从 ExtensionRouter 创建一个新的 V3ExtensionRouter，该路由器具有拦截 GET /v3 请求并使用扩展的信息更新响应的代码。扩展的信息将是扩展实现覆盖的属性。

备选方案

无。

数据模型影响

无。这将不需要数据库更改。

REST API 影响

GET /

如果 Accept 头部是 application/json-home，服务器将以 200 OK 的状态响应，并描述 REST API 的 JSON Home 文档，如上述“提议的更改”部分所述。

请注意，如果客户端使用 Accept: application/json-home 发出请求，旧服务器将以 Content-Type: application/json 返回旧的 JSON 响应，因此客户端必须验证响应中的 Content-Type 是否确实是预期的 application/json-home，然后才能使用结果。符合 HTTP 1.1 规范的服务器将在不支持提供的 Accept 头部时响应 406 Not Acceptable 错误，因此客户端也应该能够处理该响应。

客户端可以将 Accept 头部设置为类似 application/json; q=0.2, application/json-home 的值，并且服务器将在不支持 JSON Home 时返回 JSON。请注意，Keystone 服务器今天不支持这一点。Keystone 使用的 WebOb 库支持 Accept 头部处理，但 Keystone 不将其用于 Accept 头部（它用于 Accept-Language 处理）。

GET /v2.0

类似于 GET /，但返回仅用于 V2 API 和扩展的 JSON Home 文档。

GET /v3

类似于 GET /，但返回仅用于 V3 API 和扩展的 JSON Home 文档。

安全影响

无。API 是公开信息。

通知影响

无。

其他最终用户影响

python-keystoneclient 应该更改为支持获取和使用 JSON Home 文档进行发现。

性能影响

无。

其他部署者影响

无。

开发人员影响

添加新资源或使用新参数更改资源时，必须更新 JSON Home 文档。扩展必须更新 JSON Home 文档。

实现

负责人

主要负责人

blk-u <Brant Knudson>

其他贡献者

<None>

工作项

  1. 使用新的 Accept 头部和示例响应更新 Identity V3 规范和其他规范。

  2. 增强 Keystone 服务器，使其能够处理 Accept 头部，即 application/json; q=0.2, application/json-home 可能会通过将请求的 Accept 头部传递给控制器来返回 JSON Home 响应。

  3. 更改 Keystone 服务器，以便在 accept 头部是 application/json-home 时，为 /、/v2.0 和 /v3 响应 JSON Home。

  4. 更改 v2 和 v3 扩展以更新 JSON Home 响应。

  5. 编写 Tempest 测试以验证对 /、/v2.0 和 /v3 的请求，并将 Accept 设置为 application/json-home。

  6. 更新 python-keystoneclient 以能够使用 JSON Home 处理 /、/v2.0 和 /v3。

依赖项

无。

测试

Tempest 将被更改为验证 GET /、GET /v2.0 和 GET /v3 请求的响应，并将 Accept: application/json-home。

文档影响

需要更改文档以说明 Keystone 支持 JSON Home。

参考资料

[0] JSON Home

[1] Nottingham, M. “Web Linking”, RFC 5988, October 2010

[2] Discoverable home document for APIs 在 openstack-dev 邮件列表上的讨论。

[3] HTTP 1.1, section 14.1 Accept Request Header