Asp.net 设计一个RESTful API来管理目录和文件等资源

我正在设计一个RESTful API，用于管理目录和文件。
由于一些棘手的业务规则（如下所列），我很难找到一个好的资源结构和一个好的URI设计

• 有许多目录
• 一个目录有许多文件
• 文件列表只能从其父目录访问
• 可以“全局”访问特定文件（仅通过其id）
• 可以创建文件，但客户端不能指定父文件夹（因为新文件保存在特殊目录中，只能稍后移动等）

以下是一种可能的URI设计：

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

从目录中获取属性：
获取/api/directories/{directoryId}

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

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

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

创建文件：
POST/api/files

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

---

目录资源
资源URI:
/api/目录

可能的操作：

• 获取/api/目录
• 获取/api/directories/{directoryId}

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

---

文件资源
资源URI:
(?) ... 有两个URI。。。一个用于“获取全部”（“或获取多个”），另一个用于其余操作

可能的操作：

• 获取/api/directories/{directoryId}/文件
• 获取/api/files/{fileId}
• 删除/api/files/{fileId}
• POST/api/files

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

---

---

此外，我还看到一些RESTful API文档对类集合资源和类实例/元素资源（例如，请参阅）有单独的条目 这样的细粒度文档更可取吗？我想一个优势是文档中的“其他资源链接”（或“相关资源”）部分会更精确。还是我错了

---

任何想法都很感激

---

谢谢：）

我不会说你所拥有的东西特别尴尬。如果是我，我将支持以下URL：

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}

/directories/{directoryId}/files

范例很常见，但不是我最喜欢的。如果用户想要文件作为目录，他们可以使用

/files

上的查询参数。如果他们希望文件与目录同时存在，可以在

/directories/{directoryId}

上使用查询参数

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

就文档而言，没有硬性的结构。如果你不喜欢你所拥有的，改变它以避免尴尬。此外，您确实有几个目录实例。从

/directories/{directoryId}

返回的每个资源都是一个目录