基于变量值的不同 requestBody 的 API 设计

Question

我有一个 REST API uploadFeed，它根据 feedType（作为请求正文的一部分输入的字符串值）上传用户提要。不同的 feedtype 在请求正文中提供了不同的 pojo 模型。

例如，如果 feedType 是“TYPE1”，那么 API 的请求正文应如下所示：

{
 "feedType":"TYPE1",
 "inputModel": {
    "a": "somevalue"
    "b" : "somevalue",
    "c" : "somevalue",
  }
}

如果 feedType 是“TYPE2”，那么 API 的请求正文应如下所示：

{
 "feedType":"TYPE2",
  "inputModel": {
    "x": "somevalue"
    "y" : "somevalue",
    "z" : "somevalue",
  }
}

uploadFeed API 的最佳 API 设计是什么。我正在考虑有两种可能的解决方案：

Solution Proposal-1：有两个不同的 API 端点。

• feedType == Type1 的 API URI：/uploadFeed/feedType/{Type1}。这里的requestBody应该和上面提到的Type1一样

• feedType == Type2 的 API URI：/uploadFeed/feedType/{Type2}。这里的requestBody应该和上面提到的Type2一样

Solution Proposal-2：有一个端点同时存在两个模型。 对于 TYPE1 的 feedType，预期的 requestBody 应为

{
 "feedType":"TYPE1",
 "type1Model": {
    "a": "somevalue"
    "b" : "somevalue",
    "c" : "somevalue",
  },
 "type2Model" : null
}

对于 TYPE2 的 feedType，预期 requestBody 应为

{
 "feedType":"TYPE1",
 "type1Model" : null
 "type2Model": {
    "x": "somevalue"
    "y" : "somevalue",
    "z" : "somevalue",
  },
}

有没有其他可能的方法。请提出可能的最佳解决方案（不一定是这两个）。

Answer 1

虽然为每种类型使用自己的端点，甚至引入定义支持字段的特殊媒体类型可能很诱人，但这可能会导致客户端期望资源具有特定类型which they don't，并因此与模式紧密耦合，如果稍后更改可能会导致麻烦，而这在 REST 架构中随时可能发生。

由于 REST 实际上只是可浏览 Web 中使用的概念的概括，因此可以在 Web 上使用的相同技术也应该在 REST 架构中采用。

因此，您的主要目标之一应该始终是服务器正在教客户端如何实现目标。 Web 通过HTML forms 的帮助来做到这一点，它不仅教客户端支持和/或预期的输入数据，还教客户端发送请求的目标 URI、使用的 HTTP 操作以及媒体类型发送一个表示，通常由application/x-www-form-urlencoded 隐式给出。对于基于 JSON 的表示格式，hal-forms 或 ion 可能有助于实现这一目标。

所交换的表示格式应尽可能通用，但同时也应尽可能具有表现力。如果您查看 HTML，即您可以在其中表达任何内容，但毕竟它只是一个网页。描述您喜欢的汽车型号或运动队的网页的处理方式与任何其他网页相同，并且不会提示您的 Web 客户端（浏览器）该页面返回代表汽车或运动队的特定数据，尽管人类能够识别数据并将此类对象与之关联。

由于应用程序（或一般的计算机）几乎无法自行推断此类关系，因此应进一步提示客户端资源的用途，尤其是客户端获取的当前状态。在这里，使用所谓的链接关系名称是必不可少的。它们或多或少代表了 URI 附带的注释，这些注释允许 URI 随时间变化而不会失去表现力。您可能已经熟悉链接关系名称，例如 first、prev、self、next 和 last，它们在分页上下文中几乎是不言自明的，尽管可以使用此类链接关系提示客户端预计接下来将通过prefecth 请求某些相关资源（想想新闻页面，其中在文章上给出了简短的预告片，服务器可能会提示客户端可能会在下一次请求完整文章因此，客户端已经可以在后面下载文章，将其放入缓存中，并允许客户端更快地检索该内容）。然而，这样的链接关系不应该是凭空而来的，因为实际上可以在其中放置任何东西，并且客户应该知道他们表达了什么。因此，链接关系名称应为 standardized 以获得广泛采用或至少遵循 Web linking 中定义的常见做法，将链接关系名称分配给专用命名空间以防止名称冲突。

最后，作为服务器端开发人员，您的主要目标是实现某种状态机，或者如 Jim Webber (2011) 所说的 Domain Application Protocol，客户端只需执行此操作，例如在 Amazon 或您喜欢的地方订购网上商店，客户基本上只是按照服务器给出的选择来完成其购买某些物品的任务。