添加与 Openstack 一致的版本响应¶

Launchpad 蓝图: https://blueprints.launchpad.net/barbican/+spec/fix-version-api

Barbican 当前为根资源的 GET 请求返回一次性的版本信息。此蓝图要求将此响应替换为基于 json-home 的与 Openstack 一致的响应（参见 http://http://tools.ietf.org/html/draft-nottingham-json-home-03），其中包含当前支持的 API 版本。例如，将此版本信息附加到从 Keystone 服务目录检索到的端点信息后，可以促进服务的自动发现。

问题描述¶

当使用 GET 请求查询 Barbican 的根资源时，它应该使用基于 json-home 的与 Openstack 其他项目一致的版本响应。这在 2014 年 7 月 Keystone 和 Barbican 的年中会议上讨论过（有关详细信息，请参见 https://etherpad.openstack.org/p/keystone-juno-hackathon）。以下是来自 Keystone 的 json-home 类型响应的实现示例（记录在此处：https://docs.openstack.org/api/openstack-identity-service/2.0/content/Versions-d1e472.html）

{
    "choices": [
        {
            "id": "v1.0",
            "status": "DEPRECATED",
            "links": [
                {
                    "rel": "self",
                    "href": "https://identity.api.openstack.org/v1.0"
                }
            ],
            "media-types": {
                "values": [
                    {
                        "base": "application/xml",
                        "type": "application/vnd.openstack.identity+xml;version=1.0"
                    },
                    {
                        "base": "application/json",
                        "type": "application/vnd.openstack.identity+json;version=1.0"
                    }
                ]
            }
        },
        {
            "id": "v1.1",
            "status": "CURRENT",
            "links": [
                {
                    "rel": "self",
                    "href": "https://identity.api.openstack.org/v1.1"
                }
            ],
            "media-types": {
                "values": [
                    {
                        "base": "application/xml",
                        "type": "application/vnd.openstack.identity+xml;version=1.1"
                    },
                    {
                        "base": "application/json",
                        "type": "application/vnd.openstack.identity+json;version=1.1"
                    }
                ]
            }
        },
        {
            "id": "v2.0",
            "status": "BETA",
            "links": [
                {
                    "rel": "self",
                    "href": "https://identity.api.openstack.org/v2.0"
                }
            ],
            "media-types": {
                "values": [
                    {
                        "base": "application/xml",
                        "type": "application/vnd.openstack.identity+xml;version=2.0"
                    },
                    {
                        "base": "application/json",
                        "type": "application/vnd.openstack.identity+json;version=2.0"
                    }
                ]
            }
        }
    ],
    "choices_links": ""
}

当对特定版本执行 GET 操作时，应提供版本详细信息作为响应，例如此 Keystone 示例

 {
    "version": {
        "status": "stable",
        "updated": "2014-04-17T00:00:00Z",
        "media-types": [
        {
                "base": "application/json",
                "type": "application/vnd.openstack.identity-v2.0+json"
            },
            {
                "base": "application/xml",
                "type": "application/vnd.openstack.identity-v2.0+xml"
            }
        ],
        "id": "v2.0",
        "links": [
            {
                "href": "http://23.253.228.211:5000/v2.0/",
                "rel": "self"
            },
            {
                "href": "https://docs.openstack.org/api/openstack-identity-service/2.0/content/",
                "type": "text/html",
                "rel": "describedby"
            },
            {
                "href": "https://docs.openstack.org/api/openstack-identity-service/2.0/identity-dev-guide-2.0.pdf",
                "type": "application/pdf",
                "rel": "describedby"
            }
        ]
    }
}

提议的变更¶

然而，正如 Chad Lung 在 Launchpad 蓝图中指出的那样，几个项目记录并实现了上述版本响应，因此 Barbican 可以遵循相同的方法。Barbican 仅支持 JSON 格式的请求和响应，因此此蓝图将不支持或实现 XML 格式。

Keystone 的 keystone/controllers.py 实现了 GET 请求并构建了版本响应。请注意，MEDIA_TYPE_JSON 应该为 ‘application/vnd.openstack.keymanagement-%s+json’。此文件定义的 ‘Version’ 控制器通过 keystone/routers.py 模块映射到 URI 路径。最后，keystone/service.py 模块构建了最终的 WSGI 应用程序，并包含 routers.py 中定义的版本路由器。

对于 Barbican，barbican/api/controllers/versions.py 中的 VersionController 类可以类似于 Keystone 的 controllers.py 进行修改，但应重命名为 VersionsController 以处理根请求，并添加一个新的 VersionController 以返回特定的版本详细信息响应。

barbican/api/app.py 文件应修改为在当前使用 VersionController 的地方使用新的 VersionsController。请注意，虽然根版本资源将支持未经身份验证的请求，但特定的版本资源请求将需要身份验证。

此外，现在响应根资源构建版本信息仍然需要提供，以支持自动部署和测试过程。此蓝图建议在根资源上添加一个查询参数，例如 ?build_version，该参数将返回类似于当前响应的 JSON 响应，但不包含版本信息，如下所示

{
    "build": "2014.1.dev43.g22d1a96"
}

在下面的“替代方案”部分详细介绍了检索此构建信息的替代方法。

最后，Barbican Python 客户端应更新以利用这些新的版本发现信息，以增强它从 Keystone 服务目录检索到的端点信息。

备选方案¶

关于利用现有框架生成版本信息，似乎没有 Python 库实现 json-home。

关于构建版本信息，json-home 规范并未解决这个问题，尽管在 IETF 参考的附录 C 中，在标记为“未解决的问题”的部分中，似乎有一个名为“release info?” 的占位符，将来可能会解决这个问题。所以也许我们可以将构建信息添加到根版本响应中。

数据模型影响¶

无。

REST API 影响¶

根版本响应将从现在返回的一次性版本信息更改为与 Openstack 一致的响应。需要添加一个特定的版本详细信息响应（例如，对 v1/ 执行 GET 操作时）。当前包含构建版本的根响应需要修改，以便仅在指定查询参数时才返回此信息。

安全影响¶

无。

通知影响¶

无。

其他最终用户影响¶

任何依赖于当前构建版本响应的过程都需要进行修改。使用 Barbican Python 客户端的客户端需要在进行此蓝图中的更改后更新到发布版本。

性能影响¶

无。

其他部署者影响¶

无。

开发人员影响¶

无。

实现¶

负责人¶

主要负责人: jaosorior
其他潜在贡献者: john-wood-w chad-lung

工作项¶

以下 CR 将构建此蓝图

根据上述建议修改版本相关模块。

2) 在根资源上实现 build_version 查询参数以返回构建版本。

3) 更新 Barbican Python 客户端代码库以查询根资源以获取版本信息，然后将其应用于从 Keystone 服务目录检索到的端点信息。

依赖项¶

无。

测试¶

将添加版本资源的单元测试。

文档影响¶

使用 API 更改更新此页面：https://github.com/cloudkeep/barbican/wiki/Application-Programming-Interface

参考资料¶

请参阅此蓝图中嵌入的代码和文档参考。

有关 json-home 的信息可在 http://http://tools.ietf.org/html/draft-nottingham-json-home-03 找到。

有关 json-home 讨论的说明可在 2014 年 7 月 Barbican 和 Keystone 的年中会议上找到，网址为 https://etherpad.openstack.org/p/keystone-juno-hackathon。

添加与 Openstack 一致的版本响应