api - RESTful API - 在请求中传递虚假/未请求的参数时的正确行为

Question

我们正在开发一个 RESTful api，它以 JSON 编码数据的形式接受请求中的查询参数。

我们想知道当非请求/非预期参数与必需参数一起传递时，正确的行为是什么。

例如，我们可能要求给定端点上的 PUT 请求必须分别为键 name 和 surname 提供两个值:

{
    "name": "Jeff",
    "surname": "Atwood"
}

如果也传递了虚假 key (如下面示例中的颜色)怎么办？

{
    "name": "Jeff",
    "surname": "Atwood",

    "color": "red"
}

颜色的值不是预期的，也没有记录。

我们应该忽略它还是拒绝请求并返回 BAD_REQUEST 400 状态错误？

我们可以断言该请求是错误的，因为它不符合文档。也许应该警告 API 用户(她传递了该值，她会对此有所期望。)

但是我们也可以断言该请求可以被接受，因为只要提供了所需的参数，就可以满足该请求。

Answer 1

多年来，我使用了众多供应商的 RESTful API，让我从“用户”的角度为您介绍一下。

很多时候文档只是糟糕或过时的。也许参数名称已更改，也许您在属性名称上强制使用精确的大小写，也许您在文档中使用了错误的字体并且有一个看起来与 l 完全相同的 I - 是的，这些是不同的字母。

不要忽略它。而是发送一条错误消息，用易于理解的消息说明属性名称。例如“未知属性名称:颜色”。

这一件小事将大大有助于限制有关 API 消耗的支持请求。

如果您只是忽略这些参数，那么开发人员可能会认为在咒骂您的 API 时传入了有效值，因为显然 API 无法正常工作。

如果你抛出一条通用错误消息，那么开发人员就会绞尽脑汁地试图弄清楚发生了什么，并淹没你的论坛、该网站或你的电话，询问为什么你的服务器无法工作。 (我最近与一个供应商遇到了这个问题，该供应商只是不明白 404 消息不是对不正确参数的有效响应，并且文档应该反射(reflect)所使用的实际参数名称...)

现在，出于同样的原因，我希望您在缺少所需参数时也给出良好的错误消息。例如“必需的属性:名称缺失”。

<小时/>

本质上，您希望尽可能提供帮助，以便 API 的使用者能够尽可能自给自足。正如你所知，我完全不同意“仁慈”与“严厉”的崩溃。您越“亲切”，您的 API 的使用者就越有可能遇到这样的问题:他们认为他们正在做正确的事情，但从您的 API 中却得到了意想不到的行为。您不可能想出人们搞砸的所有可能方式，因此严格遵守相关错误消息将会有很大帮助。