Permissions on a rest API implementing HATEOAS

Question

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?

UPDATE

I've found the following article which suggests an answer: https://softwareengineering.stackexchange.com/questions/215975/how-to-handle-fine-grained-field-based-acl-permissions-in-a-restful-service

Answer 1

I would go with the latter: Imply permissions based on which links are present.

If the link isn't there, the user can't access the resource/perform the action. If it is, they can. That's what I'd do, because it's simple and clean and leaves little to the discretion of the front-end code. Decoupling, yo.

Alternatively, if you do want to include all the links in each response but explicitly specify which are allowed and which aren't, if you use a format such as HAL to write your links, you could extend it with a flag on each link like so:

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

Answer 2

I would go with the latter. The reason I don't like the former is because you are creating extra work for the client by requiring it to figure out the mapping between permissions and the resources they permit access to. If you use hateoas and check for the presence of relation types, this mapping is done for you by the server. It also means the uris can change without breaking the client.

I recently wrote a blog post on this area:

https://www.opencredo.com/2015/08/12/designing-rest-api-fine-grained-resources-hateoas-hal/

Answer 3

You should be using forms, not links, to provide state transition hypermedia. If you cannot provide forms in your media type, provide links to URIs which use another media type that supports forms, such as XHTML.

IANA has link relations for create-form , edit-form and delete-form for this purpose.

Also, please do not use start and pause as real link relations. If you define them yourself, they must be URIs (preferably HTTP URLs, but any URI under your control will suffice). start has a completely different meaning to what you're using it for, and pause is not defined.