如何为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设置优先级，如果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时，只需使用给定端点的验证规则进行响应即可.

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模式是一种广泛使用的-用于验证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模式很流行，因此许多验证器以不同的编程语言存在.使用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屋！