But I would go further and suggest that whether to show those shouldn't just be based on what the API can do, but what the client (and perhaps user controlling the client) can do.
As in... if they can read but not create, then show the "self" link but not the "newcomment" link.
Thus we're not just saying "our API has these endpoints", we're saying "you can do this".
> With REST, the URL for a resource never changes.
I could have an endpoint example.com/users become example.com/subsite/users. It is precisely because the URL might change that you want to give the client URLs to the next possible actions.
First, yes, you could change your "endpoint" URL, but that's not the reason for providing URLs in HATEOAS (just for the record, I hate(oas) that acronym).
You see, REST is different from most other Web services because it doesn't provide access to actions, but to resources. It can be compared to the good old SQL database -- and a resource's URL is the way to uniquely identify that resource, just like in a RDB you would have a combination of a table and a unique identifier.
The reason for providing URLs is to free the consumer from having to construct it by hand each time. In fact, an URL can change -- but not an URL to a single resource (just like you wouldn't arbitrary change a RDB record's ID); rather, a completely different resource can be provided instead.
I misused "action". Replace "to give the client URLs to the next possible actions." with "to give the client URLs so they can perform their next possible actions on related resources".
My point remains: one of the main reasons of using HATEOAS is so that you can evolve your API without breaking clients. The other main benefit is so that your client can discover your protocol by simply following hypermedia controls.
A RESTful API, in its original understanding as defined by Roy Fielding, is based on hypertext (links between resources), content types and traversal: the only "official" URI in the system (the only one which should be documented and immutable) is that of the API's root. For all other API components, the only supported access method is traversing the system until the component is reached.
As a result, there is no requirement either of URI beauty or of URI stability in a RESTful system: clients may cache URIs during traversal to speed-up subsequent operations (think bookmarks) but that's only an optional optimisation and they must know how to re-traverse the system anyway.
Stable and beautiful URIs are "cooler", but they're irrelevant to the system's RESTfulness and a correctly RESTful system (server & client) would allow randomly changing all URIs in the system (but for the root) regularly without functional breakage.
