架构设计

Question

为了学习目的，我正在为一个非常基本的闪存卡应用程序设计一个API，我想知道你们是否都认为还有什么改进的地方。

在应用程序中，文件夹包含文件夹和集合。一套包含纸牌。主页列出了我创建的任何顶级设置和文件夹(但绝不是卡片)。下面是我提出的URI模式：

这看起来可以吗？我的目标是保持URI简洁/简洁/简单，并将任何关系元数据(parentFolderId、parentSetId等)推入请求的主体。有什么想法？

Answer 1

在我看来，如果您构建API以反映数据的层次结构，API将更加简洁/简单，部分原因是该结构将是自文档化的。

实际上，我看不出客户端有一种方法可以获得特定文件夹中的集合；通过更多的结构，您可以这样做：

GET /folders/100/sets

这取决于你认为你的客户需要做什么。

另外，我可能会通过将请求列表返回到像/folders这样的集合URL来支持GET，但是如果您认为它不会因为任何原因而被使用，那么您可能希望返回405 Method Not Allowed的状态而不是错误。

除此之外，据我所知，您使用POST、PUT和DELETE似乎是正确的。

注意:有时令人困惑的一个细节是PUT也可以用来创建资源。与POST的区别在于，使用PUT，客户端已经拥有资源id并将其包含在请求正文中；使用POST，您希望服务为资源创建一个id。如果您使用自然密钥来标识资源，例如用户资源的用户名；在这种情况下，您可以使用PUT来创建或更新用户。

Answer 2

迈克·帕特里奇的答案是正确的，但我只想补充一句。

下面是是您应该发送给restful请求的响应类型的很好的参考。

具体来说，您应该将404与PUT/DELETE请求一起返回到集合(/folders)，以及返回对对象的POST请求(/folders/id)。

而且，当相关/适当时，资源往往是嵌套的。

在您的情况下，文件夹总是顶级元素，集合总是在文件夹中，卡片总是在集合中，因此：

/folders/:id/sets/:id/cards/:id应该是允许的资源

我看到它被称为挖掘-更深的路径和回溯空间惯例，在这里，简单地通过背行行距到最后一个/就可以很容易地向上移动

我提供的最后一个链接有很多示例URL，您可以在RESTful方案中使用它们。另一个示例排除了在n级可能只存在特定子资源时子资源的集合名称：

/folder/:id/:set_id/:cards_id

如果我造成更多的混乱，我很抱歉。我的观点是，有许多选择被不同的团体认为是可以接受的。无论您遵循什么约定，只要保持它的一致性，并为任何最终使用您的API的人提供良好的文档。