[muaddirac]

> Talking about documentation, purists claim that the only piece of information API should expose is the root URI, e.g. www.example.com/api. Everything else, including allowed methods, resources, content types and documents should be discovered via HATEOAS. And if URIs are not officially documented but instead should be discovered, it implies we should not rely on hard-coded URIs in our code but instead traverse the resource tree every time we use such API.

discoverable != must be discovered

This is a misconception and criticism I used to have. However, it's a misunderstanding of the point of HATEOAS - the point isn't that you can't use hard-coded URIs, but that any given URI should be reachable by traversal from the root URI.

In other words, it's fine to keep a bookmark to your favorite article, just make sure you can get to that article from the homepage, too.

(I guess I would say modulo redirects as well)