API 验证¶
https://blueprints.launchpad.net/congress/+spec/api-validation
用户（和程序）有时会提供无效的输入给 API。API 应该对此具有弹性，并拒绝错误的请求。
问题描述¶
任何不符合 API 预期格式的请求都被视为无效。无效请求应该被 API 拒绝，并提供信息以帮助纠正问题。
以下特性是 API 验证解决方案中期望的
验证应该强制执行一个声明式模型，该模型在验证实现之外可见。
声明式模型应该遵循标准格式和约定，这些格式和约定在 API 调用者的上下文中被理解。
对于跨平台 API，该模型应该可以在不了解特定编程语言的情况下使用。
该模型应该提供足够的信息，以便在相关的 API 参考资料中生成资源文档。
验证应该由一个通用框架执行，该框架可以促进声明式模型与 API 实现的绑定。
API 实现可以通过依赖框架来卸载验证，从而假设受信任的输入。
验证可以选择性地启用在 API 输出上，以促进开发和测试。
提议的变更¶
我们将引入 JSON schema 来建模每个 API 调用的预期输入和输出。
API 资源管理器将被更新以支持将 schema 与每个处理程序绑定。
在分派 API 调用时，框架将使用 ‘jsonschema’ python 验证器来验证调用体。
如果提供了可选标志，则分派器将在将响应传递到堆栈之前验证 API 处理程序响应体。
备选方案¶
其他组件，例如 neutron，已经创建了自定义验证工具。这些工具通常不如 JSON schema 丰富，并且不能解决上述许多期望的特性。
nova 项目目前正在重构他们的 API 以利用 JSON Schema 验证： https://blueprints.launchpad.net/nova/+spec/v3-api-schema
数据模型影响¶
无。
REST API 影响¶
当前的 API 提供的验证非常有限。此更改将为所有现有的 API 调用添加验证。
安全影响¶
为 API 添加验证应该通过防止意外输入来提高系统的安全性。
通知影响¶
无。
其他最终用户影响¶
无。
性能影响¶
输入验证会对 API 调用的延迟和吞吐量产生负面影响。尽管 JSON schema 具有更高的功能和灵活性，但它不一定会施加比其他验证解决方案更大的性能影响。
其他部署者影响¶
无。
开发者影响¶
在引入 API 验证后，新的 API 调用需要引入相关的 schema。
实现¶
负责人¶
- 主要负责人
pballand
- 其他贡献者
无
工作项¶
为每个 API 资源创建 JSON schema（这已经在 API 设计中完成，只需将其转换为源代码树即可。）
为 API 资源管理器添加支持，以将 schema 与资源端点绑定。
将 jsonschema 添加为运行时依赖项。
使用 jsonschema 在分派到 API 实现之前验证请求。
公开标志以支持输出验证。可选地使用 jsonschema 验证 API 结果体，然后再将其返回到 wsgi 服务器。
依赖项¶
无。
测试¶
假定 schema 验证器经过了彻底的测试。我们将通过发出应该和不应该通过 schema 验证的请求来测试是否正在执行验证。
文档影响¶
此更改本身不会影响文档。为每个 API 调用添加的 schema 应该包含在文档中。
参考资料¶
- JSON Schema 定义
- Python jsonschema 验证器
- Nova spec 用于更新验证以使用 JSON Schema
