REST Hypermedia: Should the actions be filtered based on the user's permissions?

Question

According to Roy Fielding's Hypermedia As The Engine of Application State (HATEOAS), each resource should be accompagnied with a list of actions (or links) that can be done on that resource.

If the actions are included in the entity (as apposed to using the links attribute of Json-Schema), how do I tell the user-agent that a specific option is not available to the authenticated user?

The backend could do the filtering, but then the same resource URL could have different representations depending on the authenticated user. And this does not seem REST-friendly or caching friendly.

The other option is to leave all links, and let the user-agent receive a 403 Forbidden when the action is not available to the authenticated user. This can be annoying to the user.

How to inform the user-agent on the available actions when those can change depending on the authenticated user, while remaining REST-friendly?

Answer 1

You are correct. Creating representations that vary based on user permission is not particularly cache friendly. Is it possible to classify permission variants into just a few categories? e.g. resource-low-security, resource-medium-security resource-high-security

Sometimes this approach is possible, sometimes it is not. The other aspect to consider is whether caching is critical for this particular resource. Maybe it is now?

Also, it is not necessary to wait until the user clicks on a link to find out if the user has the permissions to follow it. The client could perform an OPTIONS request on links in the background to discover which links are available and dynamically disable the links that are not accessible.

There is no single answer to this problem. Different solutions will work in different cases depending on the requirements.

Answer 2

Consider that a REST API is a website for a robot to browse.

Do websites return HTML resources (pages) containing links that you're not permitted to see?

Whether it does or not, it doesn't change how "hypermediary" the website is.

but then the same resource URL could have different representations depending on the authenticated user

Consider the same about the homepage of a website. A resource is conceptual, the home page is the concept, what it looks like changes.

How does the web deal with the caching of pages for logged-in and logged-out views?

The first way is to bar caching of those resources; not everything must be cachable, the constraint is simply that resources can be labeled accordingly.

The second is using control semantics, or headers if you're using HTTP for your REST API.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary