I've been wracking my brain and googling away for ages without coming up with a satisfactory way of handling this. I want to write a nice fully RESTful service to return resources, but the data you have permission to read (or write) variest per-resource depending on your role. So, for example, a user may be able to see their private phone number on their profile, and so may a site administrator, but another user wouldn't. An anonymous visitor might not be able to see another user's real name, but other users (and the site admin) could do. There are around 4 or 5 access levels and rules about which attributes can be read or written. The writing I'm happy with as the client can PUT changes and the server is not bound to accept them all (or at all), but the reading is my problem.
<real-name>Jim Roberts</real-name> <!-- only logged-in users should see this -->
<phone-number>+1 42424151</phone-number> <!-- only the user and admin users should see this -->
<link rel="more" href="extra-user-profile-data-for-logged-in-users"/>
<link rel="more" href="extra-user-profile-data-for-senior-users"/>
<link rel="more" href="extra-user-profile-data-for-admin-users"/>
<link rel="more" href="extra-user-profile-data-for-superadmin-users"/>
If you think about it, the
User resource that an admin client sees (with all of the fields visible) is exactly the same resource that an anonymous or less-privileged client sees. The URI is identical, but the representation they see is different.
It's similar to having the client request the representation be encoded in JSON instead of XML via the
Accept header: the server can agree to honor that request but it doesn't necessarily have to. In your case the server should return a representation appropriate to the client's supplied credentials.
Therefore, an admin might receive the content within a media type of
application/vnd.yourcompany.user.full+xml as the body returned by a GET on your
User resource, and it will contain all the fields possible.
However an anonymous user might receive the payload encoded as say,
application/vnd.yourcompany.user.limited+xml which your documentation would describe clearly as a representation that may or may not contain all the elements from the
full version. The client would have to use a flexible decoder or schema that would tolerate certain elements not being present at all.
Alternatively, you could return all the resource's information but use a special field value to indicate that a particular value was redacted:
<user> <id>jimbob</id> <real-name>--FORBIDDEN--</real-name> </user>
You could create a media type for each role, but that would introduce a strong coupling between your security scheme and your representations, and that's probably not desirable. Flexible representation schemes that use either field omission or value redaction would be more maintainable in the long term.
The final decision to make is whether or not to return links to other resources which would not be navigable based on the credentials the client supplied. In my opinion those links should always be returned, even if those credentials would not work. Why? Because the client could theoretically supply other credentials when calling those URIs. Even if they don't, the resulting
401 challenge might lead the client to eventually provide them. But if they never even get the URI, they'd be prevented from ever making that decision.