RESTful API-在请求中传递伪造/非请求参数时的正确行为 [英] RESTful API - Correct behaviour when spurious/not requested parameters are passed in the request
问题描述
我们正在开发一种RESTful api，该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.
很多时候，文档简直是糟糕的或过时的.也许更改了参数名称，也许在属性名称上使用了精确的大小写，也许您在文档中使用了错误的字体，并出现了一个与 l 完全相似的 I -是的，这些字母是不同的.
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屋！
