RESTful API - 在请求中传递虚假/未请求参数时的正确行为 [英] RESTful API - Correct behaviour when spurious/not requested parameters are passed in the request
问题描述
我们正在开发一个 RESTful api，它以 JSON 编码数据的形式接受请求中的查询参数.
We are developing a RESTful api that accepts query parameters in the request in the form of JSON encoded data.
我们想知道当非请求/非预期参数与必需参数一起传递时，正确的行为是什么.
We were wondering what is the correct behaviour when non requested/not expected parameters are passed along with the required ones.
例如，我们可能要求给定端点上的 PUT 请求必须分别为键 name 和 surname 提供恰好两个值:
For example, we may require that a PUT request on a given endpoint have to provide exactly two values respectively for the keys name and surname:
{
"name": "Jeff",
"surname": "Atwood"
}
如果也传递了一个伪密钥，例如下面示例中的 color 会怎样?
What if a spurious key is passed too, like color in the example below?
{
"name": "Jeff",
"surname": "Atwood",
"color": "red"
}
color 的值不是预期的，也没有记录.
The value for color is not expected, neither documented.
我们应该忽略它还是拒绝带有 BAD_REQUEST 400 状态错误的请求?
我们可以断言该请求是错误的，因为它不符合文档.并且可能应该警告 API 用户(她传递了值，她会期待一些东西.)
We can assert that the request is bad because it doesn't conform to the documentation. And probably the API user should be warned about it (She passed the value, she'll expects something for that.)
但我们也可以断言，请求可以被接受，因为所需的参数都提供了，它可以被满足.
But we can assert too that the request can be accepted because, as the required parameters are all provided, it can be fulfilled.
推荐答案
多年来使用了来自众多供应商的 RESTful API，让我给你一个用户"的角度.
Having used RESTful APIs from numerous vendors over the years, let me give you a "users" perspective.
很多时候文档只是糟糕或过时.也许参数名称已更改，也许您在属性名称上强制使用了精确大小写，也许您在文档中使用了错误的字体并且有一个 I 看起来与 l 完全一样- 是的，这些是不同的字母.
A lot of times documentation is simply bad or out of date. Maybe a parameter name changed, maybe you enforce exact casing on the property names, maybe you have used the wrong font in your documentation and have an I which looks exactly like an l - yes, those are different letters.
不要忽略它.相反，发送一条错误消息，用易于理解的消息说明属性名称.例如未知属性名称:颜色".
Do not ignore it. Instead, send an error message back stating the property name with an easy to understand message. For example "Unknown property name: color".
这件小事将大大有助于限制围绕 API 使用的支持请求.
This one little thing will go a long ways towards limiting support requests around consumption of your API.
如果您只是忽略参数，那么开发人员可能会认为在讨论您的 API 时正在传入有效值，因为显然该 API 无法正常工作.
If you simply ignore the parameters then a dev might think that valid values are being passed in while cussing your API because obviously the API is not working right.
如果你抛出一个通用的错误信息，那么你就会让开发人员竭尽全力找出发生了什么并淹没你的论坛，这个网站或你的电话会打电话询问为什么你的服务器不工作.(我最近与一个供应商解决了这个问题，该供应商不明白 404 消息不是对错误参数的有效响应，并且文档应该反映使用的实际参数名称...)
If you throw a generic error message then you'll have dev's pulling their hair out trying to figure out what's going on and flooding your forum, this site or your phone will calls asking why your servers don't work. (I recently went through this problem with a vendor that just didn't understand that a 404 message was not a valid response to an incorrect parameter and that the documentation should reflect the actual parameter names used...)
现在，出于同样的原因，我希望您在缺少必需参数时也能给出一个很好的错误消息.例如必需属性:缺少名称".
Now, by the same token I would expect you to also give a good error message when a required parameter is missing. For example "Required property: Name is missing".
本质上，您希望尽可能提供帮助，以便您的 API 的使用者尽可能自给自足.如您所知，我完全不同意亲切"与严厉"的细分.您越亲切"，您的 API 的使用者就越有可能遇到问题，他们认为他们正在做正确的事情，但却从您的 API 中得到了意想不到的行为.您无法想象人们会搞砸的所有可能方式，因此严格遵守相关错误消息将大有帮助.
Essentially you want to be as helpful as possible so the consumers of your API can be as self sufficient as possible. As you can tell I wholeheartedly disagree with a "gracious" vs "stern" breakdown. The more "gracious" you are, the more likely the consumers of your API are going to run into issues where they think they are doing the right thing but are getting unexpected behaviors out of your API. You can't think of all possible ways people are going to screw up so enforcing a strict adherence with relevant error messages will help out tremendously.
这篇关于RESTful API - 在请求中传递虚假/未请求参数时的正确行为的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
