rest - 如何为操作树状数据的 RESTful 服务构建 URI？

Question

假设我有树状数据，例如"file"和“文件夹”，基本操作有“列出文件夹”、“创建文件夹”、“重命名”、“创建文件”、“获取文件”。

那么如何构建 RESTful 服务的 URI？我已经尝试了几次，但所有解决方案对我来说都不是很好。

例如，如果我有 URI `http://example.com/rest/here_path_to_folder 引用的“文件夹”资源，如何列出文件夹项目？从该文件夹中获取"file"？

我看过 Amazon AWS 文档，他们使用的方法不是很干净 - 将“文件夹”路径和文件夹分隔符作为查询参数传递，这可能会导致歧义，因为不同的 URI 将引用相同的资源。我还尝试将关键字附加到路径末尾，因此列出"file"看起来像:

GET /rest/path/to/folder:list HTTP/1.1

重命名:

POST /rest/path/to/folder:rename?target=NEW_NAME HTTP/1.1

但对我来说它看起来仍然很糟糕。那么您知道在分层数据上使用 100% REST 的成功案例吗？

Answer 1

我认为使用 URI 来表示分层数据结构应该非常简单。尽管 URI 并不严格暗示层次结构(有些人喜欢保持完全不透明)，但有意义的 URI 确实具有自然的层次结构感觉，并且它们应该很好地映射到您的文件/文件夹示例。

在 RESTful 系统中，资源有一个通用接口(interface)(在您的情况下)由 HTTP 动词定义。 URI 标识资源，REST 规定不应使用它来指示您尝试执行的操作。

所以而不是

GET/rest/path/to/folder:list HTTP/1.1

我建议列出文件夹的内容(找出它的状态)，您只需使用:

GET/rest/path/to/folder HTTP/1.1

这应该返回代表该文件夹包含的文件和子文件夹的 URI 列表。然后，为了获取其中一个文件的内容，我可能会调用:

GET/rest/path/to/folder/myfile HTTP/1.1

重命名有点棘手。在某些情况下，DELETE 后跟 PUT 可以，但我猜您想保留文件夹内容而无需重新上传。一种选择是 PUT，其中正文包含新的文件夹路径，该路径以 204 和指向新创建的文件夹的 Location header 值进行响应(如“重命名标签”here 中所述) 。可选:如果您想对用户真正友好，如果有人向旧 URI 发出请求，您还可以返回 301 状态(永久移动)，并包含指向新 URI 的链接。

请记住，路径只是构成文件夹状态的属性之一，您可以使用 PUT 更新该状态，而无需引入自定义“重命名”操作。在您的例子中，您碰巧使用路径来决定您的 URI，但是状态更改导致 URI 发生更改是完全有效的。