Which values for a link-tag's rel-attribute should be used to represent a hierarchy of collections and documents?

Question

I would like to represent links to subfolders and documents in a folder in hypertext documents (possibly using HAL). Therefore, a document representing a folder should have links to the parent folder, subfolders and files contained in the folder. For the parent folder, <link rel="up" href=".." > seems to be the straightforward choice. However, I am unsure as to what is most appropriate for links to subfolders and documents contained in the folder. There are a couple of options defined in RFC-5988. However, I couldn't say which one would be most appropriate to represent a tree of folders and files.

I could come up with my own values and produce documents. For example (using HTML syntax rather then HAL for familiarity):

...
<link rel="self" href="http://example.com/some/folder/">
<link rel="up" href="http://example.com/some/">
<link rel="file" href="image1.jpg">
<link rel="file" href="image2.png">
<link rel="folder" href="subfolder/">
...

Using custom rel-attributes has the clear disadvantage of applications consuming these documents needing to have explicit support for them. Consequently, I'd rather use something that an application could understand by just following standards and best practices.

Update: AtomPub (RFC 5023) )seems to use rel="edit" on links to members of a collection. They don't have a concept for sub.collection I believe. rel="subsection" from RFC-5988 might be an option.

Answer 1

Representing a Hierarchy
One very common way to represent a hierarchy is to use the concept of parent-child relationships between levels in the hierarchy. This allows you to describe the hierarchy very generally without tying yourself to only representing folders and documents since parent-child/children can represent any hierarchy. DOM parsers, for example, use this concept heavily, since the DOM is a hierarchy.

Assuming your hierarchy is not fully balanced (ie. you can have documents at 3 levels deep, and also at 20 levels deep), you need to know what type of "node" you are at, either a collection (folder) or a leaf (document). With the notion of collection vs. leaf, and parent vs. child/children, you will be able to easily notate the relationship of all the links you should need.

Content Type
The most important part of any REST interaction is the clear definition of the content types at both the client and the server. Content types are rather obscure as far as what they need to actually be, but for your purposes it could be as little as indicating that the general resource "format" is HAL, and would also define the meaning of the parent and child rel values.

Most people forget that content types are for humans. Only the names of the content types matter to user-agents, not the contents of the content type definition. The content type definitions are used by developers (or very smart user agents) to decide how to interpret things. The user-agent just uses the name to switch interpretation modes.

Standards are not Everything
In general, it's more important for your application to represent it's own resources the way your application needs to than for you to try to shoehorn your representation(s) into some "standard". If it makes the most sense for your application to use up, folder, and file, the by all means use those link relations. The only caution I would have it to think hard about how you might want to change things down the road. Changing an API isn't the easiest thing to do, but introducing a new content type and deprecating an older one isn't too tough.

Don't get me wrong, I'm all for standards, but they, by their very nature, are almost always behind the real world. Case in point, the RCF doesn't seem to handle generic hierarchical collections of things well.