如何为 API 客户端提供端点的最新验证规则? [英] How to provide API clients with up-to-date validation rules for an endpoint?
问题描述
在我们的 API 中，我们希望实现允许客户端提取验证规则的解决方案.同步验证规则和您的密码应为 8-100 个符号"等字段下的任何有用文本会很有用.
In our API we want to implement solution which will allow clients pull validation rules. It will be useful to synchronize validation rules and any helpful text under fields like "Your password should be 8-100 symbols".
例如，当客户端请求注册验证规则时，API 响应使用此 JSON:
For example, when client request validation rules for registration, API responses with this JSON:
{
"email": {
"html5type": "email",
"maxlength": 255,
"required": true
},
"phone": {
"html5type": "tel",
"minlength": 11,
"maxlength": 11,
"pattern": "[0-9]{11}",
"required": true
},
"username": {
"html5type": "text",
"minlength": 5,
"maxlength": 18,
"pattern": "[a-z0-9_]{5,18}",
"required": true
},
"password": {
"html5type": "password",
"minlength": 8,
"maxlength": 100,
"required": true
},
"birthday": {
"html5type": "date",
"required": false
}
}
问题是关于请求此数据的最佳格式.我们想了 3 种方法.
The question is about best format to request this data. We've thought about 3 ways.
客户端应该向端点添加?rules参数并发送请求.
Client should add ?rules parameter to endpoint and send request.
所以这两个请求会有不同的行为:
So these two requests will have different behavior:
POST/v1/register-account—创建帐户.POST/v1/register-account?rules—只是响应每个字段的规则列表.
POST /v1/register-account— creates account.POST /v1/register-account?rules— just responses with rule list for each field.
但我不确定这是实现此功能的优雅方式.在我们的项目中，我们也将为过滤器实现此功能(我的意思是客户将能够获得过滤器的验证规则).所以我认为在这种情况下它会看起来有点难看:
But I don't really sure this is elegant way to implement this feature. In our project we will implement this feature for filters too (I mean client will be able to get validation rules for filters). So I think it will look a bit ugly in cases like this:
GET/v1/products?vendor=33—列出 33 供应商的产品.GET/v1/products?rules—获取所有可用过滤器的验证规则.
GET /v1/products?vendor=33— list products of 33's vendor.GET /v1/products?rules— get validation rules for all available filters.
但我的同事喜欢这种方式.
But my colleague likes this way.
另一个想法是允许客户端在 Accept 标头中设置自定义的 application/rules+json MIME 类型，API 将优先考虑这些 MIME 类型，如果 API 满足此 MIME 类型此标头将使用验证规则进行响应.
Another idea is to allow client set custom application/rules+json MIME type in Accept header which will be prioritized by the API and if API meets this MIME type in this header it will respond with validation rules.
但我们并不真正喜欢这个想法，因为 Accept 标头应该只修改响应的表示(格式).我的意思是，如果您想以 XML 格式响应，请将 application/xml 添加到标题中；如果你想在 JSON —你设置它等于 application/json.然而，自定义 MIME 类型的想法与表示无关，它绝对是另一种数据！
But we don't really like this idea because Accept header should only modify representation (format) of response. I mean if you want response in XML, you add application/xml to the header; if you want in JSON — you set it equals to application/json. However this idea with custom MIME type is not about representation, it's absolutely another sort of data!
我个人喜欢的一种方式是另一个端点.当客户端发送 GET/v1/rules?endpoint=/v1/register-account&method=POST API 时，API 只需使用给定端点的验证规则进行响应.
A way I personally like is another endpoint. When client sends GET /v1/rules?endpoint=/v1/register-account&method=POST API simply responses with validation rules for given endpoint.
我想知道你的意见.你会选择哪种方式，为什么?也许你知道这里没有列出的其他好方法.
I want to know your opinion. Which way will you choose and why? Maybe you know another good ways that are not listed here.
推荐答案
JSON Schema用于验证 JSON 数据的公认词汇.如果您使用它而不是您自己的，那将是最好的.
JSON Schema is a widely-accepted vocabulary for validating JSON data. It would be best if you use this rather than your own.
因为 JSON Schema 很流行，所以许多验证器存在于不同的编程语言中.使用 JSON 架构验证器，客户可以轻松地根据您的 JSON 架构验证他们的数据.
Because JSON Schema is popular, many validators exist in different programming languages. Using a JSON schema validator, clients can easily validate their data against your JSON schema.
至于端点，您可以简单地使用 OPTIONS HTTP 方法.所以 OPTIONS/v1/register-account 应该返回使用该端点的要求(包括架构).以这篇文章为例.
As for the endpoint, you can simply use the OPTIONS HTTP method. So OPTIONS /v1/register-account should return the requirements (including the schema) for using that endpoint. See this article as an example.
这篇关于如何为 API 客户端提供端点的最新验证规则?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
