使用 jsonschema 进行 API 验证

https://blueprints.launchpad.net/blazar/+spec/json-schema-validation

目前，Blazar 有不同的实现方式来验证请求体。此蓝图的目的是在将请求转发到任何其他 Blazar 组件之前，使用 jsonschema 验证在 API 层中的请求体。验证发送到 Blazar 服务器的请求体，接受符合资源模式的请求，并拒绝不符合模式的请求。根据请求体的内容，应该接受或拒绝请求。

问题描述

目前 Blazar 没有一致的请求验证层。一些资源在资源控制器处验证输入，而另一些则在后端失败。理想情况下，Blazar 应该有一些验证机制来捕获不允许的参数，并向用户返回验证错误。

最终用户将受益于一致且有用的反馈，无论他们正在与哪个资源交互。

用例

作为用户或开发人员，我希望观察到一致的 API 验证以及传递到 Blazar API 服务器的值。

提议的变更

验证 Blazar API 的一种可能方法是使用 jsonschema，类似于 Nova、Keystone 和 Glance (https://pypi.python.org/pypi/jsonschema)。可以使用 jsonschema 验证器对象来检查每个资源是否符合该资源的适当模式。如果验证通过，则请求可以遵循通过资源管理器到后端的现有控制流。如果请求体参数未通过资源模式指定的验证，则服务器将返回一个包装在 HTTPBadRequest 中的验证错误。

备选方案

在 API 验证框架之前，我们需要将验证代码添加到每个 API 方法中，这是一种临时性的方法。这些更改会使 API 方法代码变得混乱，并且由于验证不完整，我们需要创建多个补丁。

如果使用 JSON Schema 定义，可接受的请求格式是清晰的，并且我们将来不需要进行临时工作。

数据模型影响

无

REST API 影响

API 响应代码更改

在添加模式层时，有时 API 响应代码会发生变化。例如，在当前的 master 分支中，'computehosts' 表在数据库表中具有最大 255 个字符的 'hypervisor_hostname'。在创建主机时，用户可以传递超过 255 个字符的 'host'，这显然会以 404 HostNotFound 失败，浪费一次数据库调用。为此，我们可以仅在 'os-hosts' 的模式定义中限制 'host' 的最大长度为 255 个字符。如果用户传递超过 255 个字符，他/她将收到 400 BadRequest 响应。

API 响应错误消息

返回给用户的错误消息将会发生变化。例如，在当前的 master 分支中，如果用户没有提供主机名，例如 “name”: “” ，则 blazar-api 会返回以下错误消息

“主机 ‘’ 未找到！”

使用模式验证，将向用户返回以下错误消息

字段/属性名称的输入无效。值：<用户传递的值>。‘<用户传递的值>’ 太短。

安全影响

请求验证层输出不应损害数据或向外部用户暴露私有数据。请求验证不应在验证成功后返回任何信息。如果请求体无效，则验证层应返回无效值和/或请求所需的值，用户应该知道这些值。正在验证的资源的参数是公共信息，在 Blazar API 参考文档 中进行了描述，不包括私有数据。如果用户的私有数据验证失败，可以在验证器的错误处理中构建一个检查，以不返回私有数据的实际值。

Jsonschema 文档 注意到模式和实例的安全注意事项。

更早期的输入验证将减少恶意用户输入利用安全漏洞的能力。

通知影响

无

其他最终用户影响

无

性能影响

Blazar 将需要一些性能成本来进行全面的请求参数验证，因为对现在未验证的 API 参数的检查将会增加。

其他部署者影响

无

开发者影响

这将要求为 Blazar 贡献新扩展的开发人员提供一个适当的模式，以表示扩展的 API。

实现

负责人

主要负责人：Asmita Singh : <asmita.singh@nttdata.com>

工作项

  1. 初始验证器实现，它将包含通用的验证器代码，旨在在验证请求体的所有资源控制器之间共享。

  2. 为现有的 API 资源引入验证模式。

  3. 强制对提议的 API 添加和扩展进行验证。

  4. 删除重复的临时验证代码。

  5. 添加相关的 API 的单元和端到端测试。

  6. 添加/更新 Blazar 文档。

依赖项

无

测试

可以针对每个资源与其模式进行验证时添加一些测试。这些测试应该遍历无效的请求类型。

文档影响

  1. Blazar API 文档需要更新以反映 REST API 的更改。

  2. Blazar 开发人员文档需要更新，以解释模式验证的工作方式以及如何为新的 API 添加 json schema。

参考资料

一些有用的链接

历史记录

修订版

发布名称

描述

Train

引入