Rest – Single page app permissions represented through RESTful APIs

api-designhateoasrestweb-api

I'm trying to figure out the right way to handle permissions in a single page app that talks directly to several RESTful APIs, that implement HATEOAS.

As an example:

"As a user of my application I can view, start and pause jobs but not stop them."

The underlying rest API has the following resource:

/jobs/{id}

Which accepts GET and PUT. The GET returns a job model and the PUT accepts a job model as a request body in the form:

{
 "_links" : {
     "self" : "/jobs/12345678"
 }
 "id" : 12345678,
 "description" : "foo job",
 "state" : "STOPPED"
}

Accepted job states can be: dormant | running | paused | stopped.

The requirement says that on the UI I must have the buttons:

START, PAUSE, STOP

… and only display based on the logged in user's permissions.

From the API perspective everything works as the underlying logic on the server makes sure that the user cannot update the state to a STOPPED state when a request is made (a 401 is returned maybe).

What is the best way to inform the app / UI of the user's permissions, so it can hide any buttons that the user has no permission to action?

Should the API provide a list of permissions, maybe something like :

{
 "_links" : {
     "self" : "/permissions",
     "jobs" : "/jobs"
 }
 "permissions" : { 
     "job" : ["UPDATE", "DELETE"], 
     "job-updates" : ["START", "PAUSE"] 
  }
}

OR should the API change so that the permissions are reflected in the HATEOS links maybe something like :

{
 "_links" : {
     "self" : "/jobs/12345678",
     "start" : "/jobs/12345678/state?to=RUNNING", 
     "pause" : "/jobs/12345678/state?to=PAUSED", 
 }
 "id" : 12345678,
 "description" : "foo job",
 "state" : "DORMANT"
}

Or should it be done in a completely different way?

Best Answer

Your second approach—including in the job model only links to actions the user is actually entitled to perform—is the one I would take.

  • It keeps the focus on the resource and the actions that can be performed on it, which makes it both relatively simple and a good fit conceptually for the REST architectural style.

  • It retains on the server all the logic surrounding users and permissions instead of spreading pieces of this across server and client.

  • It neatly mirrors your design on the user-facing side of things, where buttons the user shouldn't be allowed to click simply aren't presented.

Related Topic