REST lesson learned: Consider a home link on all resources by Mark Seemann
Add home links on RESTful resources.
This suggestion is part of my REST lessons learned series of blog posts. Contrary to the previous posts, this advice doesn't originate from a lesson learned the hard way, but is more of a gentle suggestion.
When designing a level 3 RESTful API, I've found that it's often helpful to think about design issues in terms of: how would you design it if it was a web site? On web sites, we don't ask users to construct URLs and enter them into the browser's address bar. On web sites, users follow links (and fill out forms). Many well-designed web sites are actually HATEOAS services, so it makes sense to learn from them when designing RESTful APIs.
One almost universal principle for well-designed web sites is that they always have a 'home' link (usually in the top left corner). It makes sense to transfer this principle to RESTful APIs.
All the RESTful APIs that I've helped design so far have had a single 'home' resource, which acts as a starting point for all clients. This is the only published URL for the entire API. From that starting page, clients must follow (semantic) links in order to accomplish their goals.
As an example, here's a 'home' resource on a hypothetical product catalog API:
<home xmlns="http://fnaah.ploeh.dk/productcatalog/2013/05"
xmlns:atom="http://www.w3.org/2005/Atom">
<atom:link href="http://catalog.api.ploeh.dk/products/1234"
rel="http://catalog.api.ploeh.dk/docs/rels/products/discounted" />
<atom:link href="http://catalog.api.ploeh.dk/products/5678"
rel="http://catalog.api.ploeh.dk/docs/rels/products/discounted" />
<atom:link href="http://catalog.api.ploeh.dk/products/1337"
rel="http://catalog.api.ploeh.dk/docs/rels/products/discounted" />
<atom:link href="http://catalog.api.ploeh.dk/categories"
rel="http://catalog.api.ploeh.dk/docs/rels/product/categories" />
</home>
From this (rather sparse) 'home' resource, you can view each discounted product by following the discounted link, or you can browse the catalog by following the categories link.
If you follow one of the discounted links, you get a new resource:
<product xmlns="http://fnaah.ploeh.dk/productcatalog/2013/05"
xmlns:atom="http://www.w3.org/2005/Atom">
<atom:link href="http://catalog.api.ploeh.dk"
rel="http://catalog.api.ploeh.dk/docs/rels/home" />
<atom:link href="http://catalog.api.ploeh.dk/categories/chocolate"
rel="http://catalog.api.ploeh.dk/docs/rels/category" />
<atom:link href="http://catalog.api.ploeh.dk/categories/gourmet"
rel="http://catalog.api.ploeh.dk/docs/rels/category" />
<name>Fine Criollo dark chocolate</name>
<price>50 DKK</price>
<weight>100 g</weight>
</product>
Notice that in addition to the two category links, the resource representation also contains a home link, enabling the client to go back to the 'home' resource.
Having a home link on all resources is another courtesy to the client, just like avoiding 204 responses - in fact, if you can't think of anything else to return instead of 204 (No Content), at the very least, you could return a home link.
In the above examples, I didn't obfuscate the URLs, but I would do that for a real REST API. The reason I didn't obfuscate the URLs here is to make the example easier to understand.
