Public and private attributes in a resource


#1

Hi all,

We have a resource that can be accessed by both public and logged in users. However some of the attributes will only be included in the API response for logged in users.

Here is the example we are working with. Our API has a ‘book’ resource with 2 attributes:

  • The title that anyone can see (Public)
  • The description that only logged in users can see (private)

As a whole, is there a best way to present this? Is there a consensus for including excluding private data? Should we identify to private attributes in meta data?


#2

Having multiple “versions” of a model, depending on the user state, is not a good idea. It just creates more problem further down the road, like during caching.

Personally, I would advise to expose the different “views” onto the model as distinct resources in the API. Or hide the “secret” data in another resource that is referenced through a relationship.


#3

I think @OliverSalzburg’s advice is correct.

From a design perspective, I like the idea of having a related resource for the private parts. That lets you have a common resource for the public parts. But it means you will really want something like JSONAPI operations to let you save both the public and private parts together, atomically.

From an immediate implementation perspective, it’s probably simpler to create two separate resources (PublicBook vs PrivateBook). While that may require you to duplicate some things, it gives you the maximum flexibility to handle the distinct business logic on the server.


#4

Thanks All.
We will be taking an approach of making two separate resources.

I do like the idea really like @ef4 's idea of splitting the public & private into a top level ‘common’ resource with related resources that are private. That feels very OO approach to me. I hope I get an opportunity to implement that later.


#5

I have been weighing this question for a while, and I think the best answer is tangentially related to this thread. Using multiple resources for what is essentially a constrained representation of the same resource is not a good idea. I’ve written a few responses stating this, but without an alternative it wouldn’t have been super constructive, and I think this discussion will result in the correct path.

The HTTP prefer ‘return’ header is used to tailor the request content to reduce undesired traffic. The return=minimal/representation is not appropriate, and I like where @jgornick is taking the thought with my added caveats. The conversation after that is relevant, but also somewhat parallel so the discussion is incomplete.

The fully baked answer will take time, but for the short term returning the truncated representation in the anonymous (public) or public(authorized) scenarios with cache-control: no-cache will allow you get the desired result without the many issues the separate resource model will introduce. I think in the end this interesting concept may need another HTTP status code or preference header, deciding which will certainly take a bit.


Extend link objects with headers