REST Roadmap – API Hypermedia for permissions patterns
It’s been a while since my first post in the REST Roadmap series on RMM Level 2 / verbs / HTTP status codes. I’d like to continue moving up the RMM chain, looking at Hypermedia as the Level 3, according to Martin Fowler and Leon Richardson.
In the spirit of pragmatism, I’d like to tune out a lot of the chatter about media types, link formats, and the like when it comes to hypermedia for the sake of this post. We’ll focus completely on the notion of how to use Hypermedia concepts to provide security context to our users without creating an arbitrary security construct.
Let’s look at a fictionalized set of API URIs/responses, utilizing JSON. We’ll assume that we’ve authenticated to our API with something like Oauth, so we have the security context of the API consumer.
While this is certainly a boring case, thus far it’s semantically sound. However, we really don’t know what else we can do with the ‘widget’ we requested.
Now we have a sense of what we’re capable of by looking at the ‘links’ object array. The first link tells me fairly clearly that I can “create a Cog by POSTing to /widget/5/cogs”. In addition, I can “List Cogs by GETing /widget/5/cogs”. Obviously there are a variety of potential naming conventions here, but the gist is simple: provide a relationship for the related link, what kind of resource that link is, and what verb+URI to get the job done.
Our front-end developers can begin to provide actions/buttons for their users to act upon this “create Cog” link. Not only does the link indicate the capability to complete this action, it also provides the Verb+URI to make it possible. This provides our developers the opportunity to avoid hard-coding that URL, thereby reducing one more hard-coded dependency in their app.
Note that when we login as a user with less privileges, we no longer have a link for “create Cog”. For our front-end developers, this should indicate that they would not provide GUI options for creating this related resource. This should provide a more consistent user experience, where we are not prompting them to take actions which we know will not work for them (thus avoiding trips back to the server for invalid operations/400s/500s).
Obviously links can take many forms. In my experience, the typical relationships are list, item, create, update, delete. In typical pragmatic REST fashion, you should tailor this to your specific needs, while keeping in mind future sustainability.
Hopefully this gives you a start on implementing a Hypermedia strategy in your RESTful API which will give your front-end developers some quick bang for their buck. More poignantly, our application end-users will have the opportunity for a more consistent user experience while utilizing the apps that are fed from our API. Everybody wins 
I’m sure this will invite plenty of flamebait for criticisms of the hypermedia implementation noted. I invite your feedback, let’s just stay focused on pragmatic approaches, and not get too academic or dogmatically prescriptive, hopefully we can all learn something. I think it’s safe to say none of us have this figured out perfectly yet, my hope is this helps folks get the ball rolling, while getting some quick wins.
- #API makers/consumers: Do you sometimes feel like no one really gets you?
- Extend your CRUD HTTP API with sub-resources
Using the presence or lack of presence of an element as a way to convey some kind of semantic meaning is likely going to be confusing for your API consumers. “Is it missing because it’s broken or because it means something?” Whenever possible it’s best to be consistent in your response representations with explicit identifiers for when something is not allowed or is empty.
You might also eventually end up with more than one state (no access, read-only, read-write) that a simple visible/not visible semantic won’t be able to support. Best to offer complete, fully-accurate representations that don’t require an understanding of a convention (which would probably only be represented in an external documentation format, which Hypermedia-style APIs are trying to avoid).
In this pattern, I was trying to avoid utilizing a “permissions” collection, indicating all possible paths, with ‘allowed’, ‘denied’, etc. The intent is “i have a thing, what can I do with it”. If you have a list of ‘cogs’, and you are allowed to create another ‘cog’, then provide a link. What you’re describing would advocate that there is always a link to create a cog, which would have a ‘disabled’ flag or something along those lines.
In most of my reading and musing on Hypermedia as of late, the concepts are typically around the way that HTML works as being a fundamentally sound means of linking media. In a typical web experience, it would be odd to get a bunch of links of what I can possibly do, with only the links I’m allowed to do being active. I would think it more intuitive to follow the rule of least privilege, and only provide the path to actions which have the possibility of success.
In scenarios where we are linking together resources in terms of concepts like readability permissions etc I think what you’re describing makes more sense. There is a relationship between say a ‘cog’, and a ‘gear’, but you are only allowed to view a ‘gear’, not do anything with it. However, once I have a ‘gear’, shouldn’t that resource be self-descriptive enough to tell me what I can do with it?
Thanks for taking the time to put in on this, John, I appreciate it.
The links could be used as capabilities, a non-guessable token granting the authorization to process have a message processed. That way, absence of a capability is the equivalent of leaving out the link. http://waterken.sourceforge.net/
This presumes that each independent resource also provides it’s own validation of user privileges. In other words, if you found one of the URIs that are referenced in a link, you still have no capacity to do harm. This pattern intends to merely reduce hardcoding of URIs (a simple hypermedia premise) and avoid the pitfall of providing a “privileges” resource or object.
I think what you’re suggesting (non-guessable tokens) would pre-permission the use of the URI provided…which could be very interesting in some situations. However, in my scenario, I’m looking at always having a user context based on some authentication scheme, presumably by a front-end security provider/gateway.
Pingback: Scott Banwart's Blog › Distributed Weekly 197