REST包装集合中的单个资源

Question

我有一个小困境。

如果您有以下URI端点：

/item
/item/{id}

如果我向/item提出GET请求，我希望这样：

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

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

<Item>
   ...
</Item>

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

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

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

Answer 1

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

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

• twitter返回individual representation资源 包装在一个集合中
• basecamp，an 基于REST的API的早期支持者， 还follows this model

编辑：我们的API使用此HTTP status code structure

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.

Answer 3

我认为如果您考虑REST服务的消费方面，您的同事是对的，然后可以将每个响应作为集合处理。还有一件事：如果{id}不存在，您的服务会返回什么？没有？然后，消费者必须检查空结果或错误响应，单个元素或集合。根据我的经验，在任何情况下（可能是空的）获取集合是REST服务最方便的方式。