How to create a URI for a RESTful service that manages tree data?

Question

Suppose I have tree data, for example. "files" and "folders", the main operations are "list folder", "create folder", "rename", "create file", "extract file".

So how can I create a URI for a RESTful service? I tried several times, but all solutions do not look very good for me.

For example, if I have a “folder” resource referenced by the URI `http://example.com/rest/here_path_to_folder, how can I list folder items? Extract "file" from this folder?

I saw Amazon AWS documents, they use a not very clean "path to folder" approach and a folder delimiter as query arguments, this can cause ambiguity, since different URIs will refer to the same resource. I also tried adding keywords to the end of the path, so the listing of “files” looked like this:

GET /rest/path/to/folder:list HTTP/1.1 

Rename:

 POST /rest/path/to/folder:rename?target=NEW_NAME HTTP/1.1 

But it still looks awful for me. So, do you know any success stories using 100% REST for hierarchical data?

Answer 1

I think it should be pretty simple to use URIs to represent a hierarchical data structure. Although URIs do not strictly imply hierarchy (some people prefer to keep completely opaque), meaningful URIs have a natural hierarchical perception, and they should match well with your example file / folder.

In a RESTful system, resources have a common interface, which (in your case) is defined by HTTP verbs. The URI identifies the resource, REST indicates that it should not be used to indicate the operation you are trying to perform.

So instead

GET /rest/path/to/folder:list HTTP/1.1

I would suggest that you simply use the list of contents of the folder (find out its state):

GET /rest/path/to/folder HTTP/1.1

This should return a list of URIs that represent the files and subfolders contained in this folder. Then, to get the contents of one of the files, I could then call:

GET /rest/path/to/folder/myfile HTTP/1.1

Renaming is a little trickier. DELETE works in some cases, followed by PUT , but I assume that you want to save the contents of the folder without reloading. One option is PUT , where the body contains a new path to the folder in which the value 204 corresponds and the value of the Location header indicates the newly created folder (as described in the section "Renaming a tag" here ). Optional: if you want to be very friendly to your users, you can also return the status of 301 (constantly moving) with a link to the new URI if someone accesses the old URI.

Remember that a path is only one of the properties that make up the state of a folder; you can update this state using PUT without having to introduce a custom “rename” operation. In your case, you use the path to determine your URI, but it is perfectly applicable for a state change to cause a change in the URI.