基于可变值的具有不同requestBody的API设计

问题描述 投票:0回答:1

我有一个REST API uploadFeed,该API根据feedType(将字符串值作为输入输入到请求主体中)上传用户feed。不同的供稿类型在请求主体中总共提供了不同的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设计是什么。我正在考虑两种可能的解决方案:

解决方案-1:有两个不同的API端点。

  • feedType的API URI ==类型1:/ uploadFeed / feedType / {Type1}。这里的requestBody应该和上面提到的Type1

  • 相同。
  • feedType的API URI == Type2:/ uploadFeed / feedType / {Type2}。这里的requestBody应该和上面提到的Type2

  • 相同。

Solution Proposal-2:具有两个模型都存在的一个端点。对于feedType为TYPE1的预期requestBody应为

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

对于feedType为TYPE2,预期的requestBody应为

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

还有其他可能的方法。请提出可能的最佳解决方案(不一定是这两者中的一种)。

rest api api-design
1个回答
0
投票

虽然可能很想为每种类型使用自己的终结点,或者甚至引入定义支持字段的特殊媒体类型,但这可能会导致客户期望资源具有特定类型which they don't和因此与架构紧密耦合,如果以后再更改,可能会引起麻烦,这在REST架构中可能随时发生。

由于REST实际上只是可浏览Web中所用概念的概括,因此在REST体系结构中应采用可以在Web上使用的相同技术。

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

交换的表示形式应尽可能通用,但在相同方面也应尽可能具有表现力。毕竟,如果您查看HTML,则可以从字面上表达其中的任何内容,但这仅仅是一个网页。描述您喜欢的汽车模型或运动队的网页的处理方式与任何其他网页相同,并且不会暗示您的Web客户端(浏览器)该页面返回代表汽车或运动队的特定数据,尽管人类可以识别数据并将此类对象与之关联。

由于应用程序(或一般而言,计算机)几乎无法自行推断出这种关系,因此应进一步向客户端提示资源的用途,尤其是关于客户端获取的当前状态。在这里,必须使用所谓的链接关系名称。它们或多或少表示URI附带的注释,这些注释使URI可以随时间变化而不会失去表达性。您可能已经熟悉链接关系名称,例如firstprevselfnextlast,它们在分页的上下文中几乎是不言自明的,尽管可以使用此类链接关系通过prefecth来暗示客户希望接下来将请求一些相关资源(例如新闻页面,其中在文章上给出了简短的预告片,而服务器可能暗示客户下一步可能会请求完整的文章这样客户就可以下载后面的文章,将其放入缓存中,并允许客户更快地检索到该内容。但是,这样的链接关系不应该来自任何地方,因为可以在字面上放置任何内容,客户应该知道他们表达的内容。因此,此类链接关系名称应为standardized以得到广泛采用,或至少遵循Web linking中定义的通用做法,该惯例将链接关系名称分配给专用名称空间以防止名称冲突。

最后,作为服务器端开发人员,您的主要目标是实现某种状态机,或称为Jim Webber (2011)称为状态机Domain Application Protocol,客户端可以照此执行,例如在Amazon或您首选的Web站点上订购。商店,客户基本上只是遵循服务器给出的选择来完成其购买某些物品的任务。

© www.soinside.com 2019 - 2024. All rights reserved.