用于资源集的良好REST API设计

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

使用REST很清楚如何在资源上进行操作，例如

PUT /users/{userId} - updates the user with userId
GET /users/{userId} - reads the user with userId

类似地用于资源集

POST /users - creates a new user
GET /users/{userId}/books - reads list of books from a user
GET /users/{userId}/books?filter=x - reads list of books from a user with specific filter

例如，如果要在资源集上进行更详细的操作，该怎么办

  1. 与请求正文一起，将书籍清单添加到现有清单中并接受重复的书籍（基本上是将清单串联在一起）
POST /users/{userId}/books 
or PUT /users/{userId}/books 
or PATCH?
or POST /users/{userId}/books/concatenate
  1. 使用请求正文，将书籍列表添加到现有列表中，但没有重复项（基本上是合并列表）
POST /users/{userId}/books 
or PUT /users/{userId}/books 
or PATCH?
or POST /users/{userId}/books/merge
  1. 也用于删除部分资源集：与请求正文一起，从现有列表中删除具有特定属性的书籍列表
POST /users/{userId}/books/delete?category=x 
or DELETE /users/{userId}/books?category=x
  1. 或删除资源集中的所有资源：
POST /users/{userId}/books/delete_all 
or DELETE /users/{userId}/books

将感谢一些提示或指导原则

rest api post put http-delete
1个回答
0
投票
从REST的角度来看，

“资源集”是一种虚构。只有资源。就通用HTTP组件而言，以下URI暗含_no关系：

/users
/users/{userId}
/users/{userId}/books
/users/{userId}/books?filter=x
/users/{userId}/books/concatenate

它们彼此完全独立；例如，DELETE /users并不暗示anything关于其他资源。

我们人类倾向于以有意义的模式分配标识符，但是机器不在乎。

与请求正文一起，将书籍清单添加到现有清单中并接受重复的书籍（基本上是将清单串联在一起）

PUT和PATCH具有远程创作语义；它们的行为就像您尝试在服务器上编辑文件的副本时所期望的那样。您GET资源的当前表示形式的副本，对本地副本进行编辑，然后请求服务器更改其副本以匹配您的副本。使用PUT，可以发送资源表示的完整副本。使用PATCH，您将发送一个补丁文件来描述所做的更改。

It's okay to use POST; HTML仅使用GET和POST就很好了，网络接管了整个世界。

您不需要用于POST的单独资源；您可以根据需要使用一个，但没有必要。

使用请求正文，将书籍列表添加到现有列表中，但没有重复项（基本上是合并列表）

没什么不同；我们在HTTP中达成的共识是请求和响应消息的semantics。服务器选择要做的是实现方面的考虑。参见Fielding 2002。

因此，如果我向您发送包含重复条目的列表的表示，并且您删除了重复项，那是“很好”；您只需要谨慎对待您的回复即可确保您不暗示自己照原样接受了所要求的陈述。

使用PATCH，这有点模糊，因为RFC描述了all or nothing语义，但是基于所使用的语言，可以合理地推断实现也受到限制。

也用于删除部分资源集：使用请求主体，从现有列表中删除具有特定属性的书籍列表

仔细阅读RFC 7231：DELETE并不完全代表您的示例所暗示的意思。 DELETE打破了键（目标uri）和值（资源表示形式）之间的关联，但这并不一定意味着“而且还要垃圾回收表示形式”。

相同的想法表达了另一种方式-假设我来自服务器GET /list-of-books，返回的表示形式是三本书的列表。如果我想让该资源返回一个empty列表的表示形式，则DELETE是错误的工具。 DELETE告诉服务器，我希望将来对GET /list-of-books的调用返回404 Not Found或可能返回410 Gone。如果我真正想要的是带有空列表的200 OK，则需要PUT / PATCH / POST / etc。资源。

删除资源集中的所有资源

与以前相同的问题。

使用REST很清楚如何对资源进行操作

这是问题-尚不清楚如何对资源进行操作。网络上充斥着充斥整个网络的文献（我们使用REST来获取破坏REST课程的文档-极具讽刺意味）。

REST包括统一接口作为约束。在HTTP中，该接口实际上是文档存储。 PUT和PATCH只需编辑文档内容-如果您的域是贫乏的或声明性的，这是完全令人满意的。对于我们没有标准化语义的任何其他内容，我们使用POST。

参见Jim Webber，2011：“您必须学习如何使用HTTP触发业务活动，这是在网络上移动文档的副作用。”

最新问题
© www.soinside.com 2019 - 2024. All rights reserved.