We design RESTful API for our system. 90% of resources have dependency from other resource called as "user", for example. "User" also can be used as an independent resource. We found two ways how to reflect it in API URIs.

First-level resource. Pros: transparently for clients what resources depends and what doesn't. Cons: what to do if some new resource obtain dependency from "user" or conversely lose that dependency).


Required parameter. Pros: easy to add and remove the dependence. Cons: not transparently for clients.


Does exist any best practice for such case?

  • 1
    You could place the token in the header, Standards like JOSE (JWT/JWE/JWS) follows this. Commented Aug 5, 2016 at 19:54

1 Answer 1


I would suggest a third solution: use Hypermedia As The Engine Of Application State (HATEOAS).

Basically HATEOAS is about including links in resources representations to other resources. More specifically, it allows client to know what actions can be taken depending on the provided links.

In your case, it does not have the Cons of solution 1 and 2. Because you do not rely on any hierarchy and it's transparent for client since links are provided in the resources representations of your "dependent resources".

Let's say that you have ressources R1 ("token" ?), R2 ("guest" ?), R3, etc. that have a dependency with your "user" resource. Just add a link in the resources representations of R1, R2, R3, etc. to the URI of your "user" resource and it's done.

  • Thanks for interesting conception! But seems like that it does not resolve the main issue - concrete set of tokens depends on the concrete client. As example: for client "guest" token "1", for client "admin" token "2". For now - token collection can be retrieved only for concrete user. But in future this may change and will be a separate resource "token" for any users. Then it is necessary to keep the two URIs: /user/:name/token and /token. Commented Aug 5, 2016 at 21:09
  • So basically you would have in the resource representation of /user/:name/token a subset of the resource representation of /token ? Because resource representation of /token contains a collection of token linked to a client ? Commented Aug 5, 2016 at 21:38
  • We have many resources which now can be retrieved only for concrete user, as /user/:name/token. But it's just for now. In future some of this resources may take posibility to retrieve without user, as /token, for example. Commented Aug 6, 2016 at 8:47
  • That's perfectly valid with my answer. Basically you want to avoid coupling resources in URI (token& user/:name resource). Thus your only option is to use an field in your /token resource referencing a /user/:name like an id for example (that's very similiar to foreign key in database!),. That's basically your solution 2. However, if a client want to know further information about the the user when he retrieve the resource /token, you should also include links... that's what i said in my answer :) Commented Aug 6, 2016 at 15:59

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.