Restful API : Is it meaningful to send PUT without enclosed entity?

Question

考虑以下场景:

有两个现有实体:shopping card #1 和item #1。我想将 item #1 添加到 shopping card #1。有两种可能的方法来设计 Restful api:

1:没有 body :

PUT http://myshoppingsite.com/api/shoppingcards/1/items/1
Host: myshoppingsite.com

2:有主体(有封闭实体):

PUT http://myshoppingsite.com/api/shoppingcards/1/items/
Host: myshoppingsite.com    

{itemId: "1"}

其实我无法决定哪个更好，哪个更有意义。有什么想法吗？

(注意:由于幂等性，我认为 http 方法应该是 PUT，但这不是我的问题。)

PS:第一个设计的问题是请求中没有这样的封闭实体。在语言上 put 是一个及物动词，所以我希望有人 puts something 某处。我认为 HTTP 世界也有同样的故事。

Answer 1

PUT 是一个 HTTP 动词，应该创建或替换目标 URI，因此这会使您的第一个选项立即出错。此请求应该替换所有您购物车中的商品:

PUT http://myshoppingsite.com/api/shoppingcards/1/items/

因为您想添加 东西到您的购物车，所以这不是一个选项。这实际上留下了两个选择。第一种:常见的:

POST http://myshoppingsite.com/api/shoppingcards/1/items/

POST 可能有很多含义，但在 REST 服务的上下文中，它通常用于将某些内容附加到集合中。但是，您提到您想要幂等性。您在这里有两个选择，首先您可以仍然使用POST 并在您的API 上下文中保证请求将 是幂等的。使用 POST 并不意味着它根据定义是非幂等的，它只是意味着 HTTP 规范本身并不能保证它。这不会阻止您使请求幂等。

另一个选项确实是PUT:

PUT http://myshoppingsite.com/api/shoppingcards/1/items/1

不过您对此有所顾虑，因为在您的 API 上下文中您说请求正文最终会为空。

原因是你在 url 的最后一个 /1 上附加了 special，我认为这是错误的。如果您想遵循 REST 最佳实践，那么 url 不应该有任何特殊含义。

如果您坚持使用 PUT，我认为一个更明智的方法是摆脱“id”的概念。该概念仅存在于您的数据库中，不应进入 API。

相反，我想您的服务有一个产品列表，例如这个:

http://myshoppingsite.com/products/1

要使用 PUT 将产品添加到购物车，此请求可能如下所示:

PUT http://myshoppingsite/api/shoppingcards/1/items/[completely-arbitrary-string-or-perhaps-a-uuid]
Content-Type: application/json

{
   "product" : "http://myshoppingsite.com/products/1",
   "quantity" : 5
}

不过就我个人而言，我只会使用 POST。

问:应该有你添加的产品的一些信息吧？是的，该信息是 Uril 的一部分。为什么不好？

我不是说它不好，我是说它不是 RESTful。拿起任何有关 REST 的书籍，您都会看到这一点。这也可能是开始阅读更多关于 REST 是什么的好地方:

http://martinfowler.com/articles/richardsonMaturityModel.html

我个人认为很少有人构建真正的 RESTful 服务。这就是为什么我还想特别指出，我不想说这对您的特定 API 是好是坏，它根本不是 RESTful。

如果我不关心这些原则并希望保留我的特殊含义 url 方案怎么办？

这是一个公平的观点，但我们已经超出了这里的原始问题。如果您想设计一个 API，其中 url 的最后一位实际上是购物车中商品的“表示”，那么是的，我同意将它也放在正文中是多余的。

在那种情况下，我会说，让请求正文为空。我猜只是不要称它为 REST。