Sign up ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free.

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:


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?

share|improve this question
I may be misunderstanding the question but as we're talking about urls is SEO an issue? – Jon Hopkins Dec 2 '10 at 11:21
SEO is not an issue, no. I'm basically asking the best logical URL structure for a self referencing resource. – Matt Brailsford Dec 2 '10 at 11:32
That seems pretty straight forward to me. – Tim Post Dec 2 '10 at 11:43
How deep can that structure go? – Martijn Verburg Dec 2 '10 at 13:09
@Martijn the depth is un-restricted – Matt Brailsford Dec 17 '10 at 12:19

2 Answers 2

What comes to my mind is: do not let you RESTful API reflect the recursivity in the URL itself. Come to think of it, your resource is only the documents.

If you have your documents stored physically according to the recursive structure, create a mapping to an unique ID, and use the ID in the URL:


Now, if you have your documents like this:

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

the request would consult this url for /abc/asd document

GET /rest/documents/2

So, now you have to provide users of your API with means to traverse your structure with little effort. That could be done by wrapping your response payload (document) into an object, containing additional traversal information, like this:

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

provided that you expect users not to create too much documents in a single level, you can include a list of children into the response. If that's not the case you could offer user to retrieve child document IDs like so, allowing e.g. for paging the results via querystring parameters:

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

Finally, speaking of querystring parameters, you could also supply the path information directly through the querystring parameters:

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

All of the approaches mentioned expect that the plain GET /rest/documents returns only root documents.

share|improve this answer

Something like this perhaps:


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.

share|improve this answer

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.