REST包装集合中的单个资源

Question

我有一个小困境.

如果您有以下URI端点:

/item
/item/{id}

如果我发出GET请求,/item我希望这样:

<Items>
   <Item>...</Item>
   <Item>...</Item>
   ...
</Items>

如果我向/ item/{id}发出GET请求,我希望这样:

<Item>
   ...
</Item>

我的一些团队成员争辩说我们应该设计API,这样当有人为/ item/{id}进行GET时,它应该作为单个元素的集合返回.像这样:

<Items>
   <Item>...</Item>
</Items>

这对我来说似乎不对.你也觉得不对吗？请解释原因,因此我可能会说服自己使用资源的永久包装版本或我的同伴开发人员使用非包装的单一资源.

Answer 1

似乎违反直觉.您可以通过一种方法从两个GET方法中读取数据,从而节省客户端的代码工作量.这当然可以通过使用额外的代码将单个GET方法包装在集合中来抵消.

如果你想要真实世界的例子,

编辑:我们的API使用此HTTP状态代码结构

Answer 2

最重要的是,这个问题没有正确和错误的答案.

但是,这就是我的想法.

如果你想返回一个项目,我倾向于这样做:

GET /Item/{Id}

=>
<Item>
  ...
</Item>

如果{Id}不存在,则服务器应返回404.

如果我想要退回一系列物品,我会这么做

GET /Items
=>
<Items>
 <Item>...</Item>
 <Item>...</Item>
</Items>

如果没有项目,那么它应该返回一个带有空<Items/>元素的200 .

如果真的让客户端更容易处理只有一个元素的集合,那么你可以做这样的事情.

GET /Items?Id={Id}
=>
<Items>
  <Item> ... </Item>
</Items>

这里的区别在于,如果{Id}不存在,那么我倾向于返回200而不是404.