0

I’m redesigning the REST API for a small SaaS I built. Currently there’s a route /entries that doesn’t require any authentication. However, if the client authenticates with sufficient privileges, the server will send additional information (ex: the account associated with each entry).

The main problem I see with this is that a client attempting to request protected data with insufficient privileges will still receive a 200 response, but without the expected data, instead of a 401 Unauthorized.

The alternatives I came up with are:

  1. Split the endpoint into two endpoints, ex /entries and /admin/entries. The problem with this approach is that there are now two different endpoints for essentially the same resource. However, it has the advantage of being easy to document with OpenAPI. (Additionally, it allows for the addition of a /entries/:id/account endpoint.)

  2. Accept a query parameter ?admin=true. This option is harder to document. On the other hand, it avoids having multiple URIs for a single entry.

Is there a standard way to structure something like this?

Related question: Different RESTful representations of the same resource

Benjy Wiener
  • 1,085
  • 2
  • 9
  • 27
  • I think this question is too opinion based for this site. The bottom line is REST really wasn't built to idiomatically handle complex logic like this. This is one of the reasons why GraphQL was built. Both of the approaches you described are deployed in the wild at large tech companies. The decision to pick one over the other is usually driven by the exact use case. For example "easy to document" becomes a whole different thing if the customer is external & have their own complex subtenancy system vs. if it's just internal admins. Either way, you'll have to pick according your own use case – sinanspd Oct 25 '21 at 08:38

1 Answers1

1

The alternatives I came up with are

Note that, as far as HTTP/REST are concerned, your two alternatives are the same: in both cases you are introducing a new resource.

The fact that in one case you use path segments to distinguish the two identifiers and in the other case you are using the query part doesn't change the fact that you have two resources.

Having two resources with the same information is fine - imagine two web pages built from the same information.

It's a trade off - the HTTP application isn't going to know that these resources have common information, and so won't know that invalidating one cached resource should also invalidate the other. So just like with web pages, you can get into situations where the representations that you have in your cache aren't consistent with each other.

Sometimes, the right answer is to use links between different resources - have "the" information in one place, and everywhere else has links that allow you to find that one place. Again, trade-offs.

HTTP isn't an infinitely flexible application protocol. It's really good at transferring documents over a network, especially at "web scale".

There have been attempts at using Link headers to trigger invalidation of other cached resources, but as far as I have been able to tell, none of them has made it past the proposal stage.

VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91