Question

我正在设计一个 RESTful API ，用于处理（以及其他）管理目录和文件。
由于一些棘手的业务规则（如下所列），我在寻找良好的资源结构和良好的URI设计方面遇到了一些麻烦......

目录很多。
目录有很多文件。
只能从其父目录访问文件列表。
可以访问特定文件＆＃34;全局＆＃34; （仅限其身份证明）
可以创建文件，但客户端不能指定父文件夹（因为新文件保存在特殊目录中，只能在以后移动等）。

这是一个可能的URI设计：

获取所有目录：
GET / api /目录

获取目录的属性：
GET / api / directories / {directoryId}

获取目录中的文件：
GET / api / directories / {directoryId} / files

获取文件：
GET / api / files / {fileId}

删除文件：
DELETE / api / files / {fileId}

创建文件：
POST / api / files

这是一个尴尬的设计吗？如果是，为什么？
此外，如果要记录此 RESTful API ，这也有点尴尬：

目录资源
资源URI：
/ API /目录

可能的操作：

GET / api /目录
GET / api / directories / {directoryId}

与其他资源的链接：
（？）如何写这个？有一个指向文件资源的链接，但只有在使用第二个操作时才能访问该链接。

文件资源
资源URI：
（？）...有两个URI ...一个用于＆＃34;得到全部＆＃34; （＆＃34;或得到许多＆＃34;）和其余的操作。

可能的操作：

GET / api / directories / {directoryId} / files
GET / api / files / {fileId}
DELETE / api / files / {fileId}
POST / api / files

与其他资源的链接：
链接到目录资源 - 请注意单数（？）
严格来说，没有目录资源，但有一个目录 - 我应该单独处理这两个（目录VS目录）吗？请在最后看到问题。此外，此链接仅在前两个操作中可用...如何在指定时更精确？

此外，我发现一些RESTful API文档具有集合类资源和实例/元素类似资源的单独条目（例如，见this）这样的粒度文档是否更可取？我想一个优势就是＆＃34;链接到其他资源＆＃34; （或＆＃34;相关资源＆＃34;）文档部分会更精确。或者我错了吗？

任何想法都表示赞赏！谢谢:)）

Answer 1

我不会说你拥有的东西特别尴尬。如果是我，我会支持这些网址：

GET /directories

GET /directories/{directoryId}    // includes a link to the files in the directory, such as /files?directoryId={directoryId}
GET /directories/{directoryId}?expand=files    // includes a child collection with links to each individual file resource, and possibly other metadata as well

GET /files
GET /files?directoryId={directoryId}
POST /files

GET /files/{fileId}
DELETE /files/{fileId}

{p> /directories/{directoryId}/files范例很常见，但不是我最喜欢的范例。如果用户想要目录的文件，他们可以使用/files上的查询参数。如果他们希望文件与目录同时存在，则可以使用/directories/{directoryId}上的查询参数。

这当然都是主观的。如果不知道所有细节，没有人能够给你一个正确的答案。

就文档而言，没有硬性和快速的结构。如果您不喜欢自己拥有的东西，请更改它以避免尴尬。此外，您有多个目录实例。从/directories/{directoryId}返回的每个资源都是目录。

设计RESTful API以将资源作为目录和文件进行管理

1 个答案: