递归资源的最佳RESTful URL结构是什么？

我正在为树状资源结构创建RESTfull服务，并且想知道最佳的URL结构是什么？

我有三个要求：

能够获得根资源的集合
能够获得个人资源
能够收集儿童资源

我目前的想法是：

/rest/documents
/rest/documents/{id}
/rest/documents/{id}/documents

我还考虑过使用单数/复数形式来表示列表或单个元素，但是我知道我将拥有与单数相同的复数形式的资源，因此决定对此进行反对。

有人对以上有任何想法吗？还是有其他/更好的方式来构造这个？

web-services

— 马特·布雷尔斯福德
source

我可能会误解这个问题，但是在我们谈论网址时，SEO是一个问题吗？

— 乔恩·霍普金斯

SEO不是问题，不是。我基本上是在询问用于自引用资源的最佳逻辑URL结构。

— 马特·布雷尔斯福德

对我来说，这似乎很简单。

— Tim Post

这种结构能走多深？

— Martijn Verburg

@Martijn的深度不受限制

— Matt Brailsford 2010年

Answers:

我想到的是：不要让RESTful API反映URL本身的递归性。想到这一点，您的资源只是文档。

如果您根据递归结构在物理上存储了文档，请创建到唯一ID的映射，然后在URL中使用该ID：

/rest/documents/{id}

现在，如果您有这样的文档：

| DocumentName | DocumentPath | DocumentID |
--------------------------------------------
| abc | / abc | 1 |
| asd | / abc / asd | 2 |
| asd | / asd | 3 |
| 嘘 / abc / asd / boo | 4 |
| 嘿 / abc / asd / hey | 5 |

该请求将查询此URL以获取/abc/asd文档

GET /rest/documents/2

因此，现在您必须为您的API用户提供轻松浏览结构的方法。这可以通过将响应有效负载（文档）包装到一个对象中来完成，该对象包含其他遍历信息，如下所示：

{
   data: { /* your document goes here */ },
   parent: {"abc": 1 },
   children: [ { "boo": 4 }, { "hey": 5} ]
}

如果您希望用户不要在单个级别中创建过多的文档，则可以在响应中包括子级列表。如果不是这种情况，则可以为用户提供检索子文档ID的方法，例如允许通过querystring参数分页结果：

GET /rest/documents/2/children?page=2&size=50

最后，说到querystring参数，您还可以直接通过querystring参数提供路径信息：

GET /rest/documents?path=somepath&page=1&size=42

提到的所有方法都希望平原GET /rest/documents仅返回根文档。

— 内奇金
source

好主意。但是，如果子文档包含在文档的响应中，则从API尚不清楚与子文档的关系。如果文档还具有另一个子资源，例如注释，则通常应使用/ documents / {id} / questions访问文档的问题。为了保持一致并在API中明确说明与子文档的关系，我建议应该通过/ documents / {id} / child-documents访问子文档。返回的表示形式就是文档，就像/ documents / {id}一样。因此，您在此处描述的其余内容仍然适用。

— 内森·沃德

大概是这样的：

/rest/{rootEntity}/Item/{leafEntity}/{id}
/rest/{entity}/ItemList
/rest/{entity}/ItemList/{leafEntity}

其中{rootEntity}是集合的起点，{leafEntity}是树中任何已命名的叶子节点。

您可以在上面的任何参数中附加一些参数以选择“最新”或“全部”或其他内容。

— 加里·罗
source