9

JSON API REST endpoint with permissions-restricted fields

I am working on a JSON API-compliant REST api. Some endpoints contain fields that should be restricted (read-only or not available) for certain users.

What is the best way to architect the api to allow that certain users have access to certain fields, while others do not? By "best", I mean:

  • Most compliant with REST standards, ideally JSON API standards
  • Most clarity in terms of preventing bugs and confusion on behalf of clients consuming the API

I am considering the following options, each with their set of concerns/ questions. I would be more than grateful for any other solutions!

Option 1: Return null on restricted fields for users without permissions

  • Different data values would be returned per-user. Is this strictly anti-REST?
  • Lack of distinction between null meaning "null value" and null meaning "You don't have access to this"
  • In REST/ JSON API architecture, is it okay for an endpoint to return different data per user, based on permissions? I have the impression that this would be contrary to the spirit of resource-based REST architecture, but I could not find anything specific to point to in any doc or standard (e.g. JSON API). Also applies to Option 2.
  • Is there any paradigm for adding some sort of "You don't have access" flag in the resource's metadata?

Option 2: Exclude restricted fields entirely for users without permissions

  • Different data values would be returned per-user. Is this strictly anti-REST?
  • Possibility of "undefined" errors in client, when trying to retrieve field value

Option 3: Move restricted field(s) onto another endpoint, available as an ?include='field_name' relation for those with permission

  • Example: /api/entity includes attribute field "cost" which is only available to Admin users. Admin users can request cost data via GET /api/entity?include=cost. For all users, "cost" is exposed as a relation in the resource object, with a "type" and "id".
  • This is the option I am leaning toward. The main con here is endpoint clutter. I have a lot of relations that would need to be made into separate endpoints, simply to support a permissions-quarantined data on an already-existing endpoint.
  • In the JSON API specs, I am having trouble determining if it's ok for an endpoint to exist as a relation only, e.g. can we have /api/entity/1/cost, but NOT have a top-level api endpoint, /api/cost. My assumption is that if a resource has a "type" (in this case, the relation type being 'cost'), it also has to live on a top-level endpoint.
  • In this scenario, the client could get a 401: Unauthorized error response if a non-admin user tries to GET /api/entity?include=cost or GET /api/cost/:id

Note: I have already built a separate permissions schema so that the client can determine which CRUD privileges the user has, per top-level endpoint, before making any requests. Permission sets are indexed by resource type.

Any help on the matter would be very much appreciated! And if anything needs to be clarified, feel free to ask.

2
  • returning different data formats for the same endpoint is not anti-REST. That's what Content-Type is for. I feel like the most RESTful way would be to use option 2, making use of different Content-Types and Accept headers. I'm curious, what did you use, in the end?
    – jpbochi
    Apr 20, 2021 at 10:01
  • 1
    @jpbochi This was a few years ago, but if I recall correctly I believe my team and I went with Option 2, making sure to provide documentation.
    – g.carey
    Jun 29, 2021 at 14:23

1 Answer 1

1

I would definitely not use undefined or null to indicate fields that the user is not allowed to see. To me, that feels like a lie and represents that the data is really not there. They would have to really know your API in order to get a grasp of what is really going on.

I would recommend something more like your 3rd option, except I would make it a different endpoint altogether. So in your example, the endpoints would be:

/api/entity/1/cost

and for admins

/api/admin/entity/1/cost

or something like that.

This way your server code for the admin endpoint could just be focused on authenticating this admin user and getting them back all the fields that they have visibility on. If a non admin user tries to hit that route, reject them with an unauthorized status code.

I'm not saying that you should not implement the GET param to be able to specify fields as well. You can if you want to, but I don't think it just won't be necessary in this case.

1
  • 1
    Thank you @arjabbar. I agree that I should avoid option 1, as returning null for a restricted field value would lead to problems. I am still considering option 2 (excluding restricted fields entirely) and option 3 (separate endpoints). Your /api/group/entity solution is a nice suggestion & would work for some applications. However, in my case the permissions system is too granular to create an entirely new endpoint for each possible combination of user permissions associated with the data.
    – g.carey
    Jan 14, 2016 at 19:49

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.