What's the best RESTful URL structure for a recursive resource?

Question

I'm creating a RESTfull service for a tree-like resource structure and was wondering what the best URL structure would be?

I have three requirements:

1. be able to get a collection of root resources
2. be able to get an individual resource
3. be able to get a collection of child resources

My current thought is:

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

I was also thinking of going the singular / plural routes to denote lists or individual elements, but I know I'm going to have a resource that is the same plural as it is singular, so decided against this.

Does anybody have any thoughts on the above? or have a different / better way of structuring this?

Many thanks

Matt

Answer 1

Something like this perhaps:

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

where {rootEntity} is the starting point of your collection, {leafEntity} is any named leaf node within your tree.

You could append a few parameters any of the above to select, say, Latest or All or something.