Question

I have written a REST server based on RESTEasy.

In some of the resources, collections of objects are returned instead of single objects: the method that responds to the URL “/users/{user_id}” returns a single “user” object, but the method that responds to the URL “/users” returns all users. In the former case, I can include an HTTP header “Content-Location: URL” (although this is redundant since the caller has the correct URL). In the latter case, each item in the returned collection has its own location. I was thinking of added an XML attribute to each item specifying its location:

<users>
  <user location="/users/1234">
    ...
  </user>
  <user location="/users/5678">
    ...
  </user>
</users>

Is there some conventional way of returning this information?

Answer 1

This is a very common practice when designing hypermedia APIs. It is also highly recommended. There is no official "right" way of doing it, however one media type that has very explicit rules as to how you can do it is hal. See http://stateless.co/hal_specification.html

In hal your document would look like:

<resource href="/users">
    <resource rel="item" href="/users/1234">
        ...
    </resource>
    <resource rel="item" href="/users/5678">
        ...
    </resource>
</resource>

I picked the term "item" because it has been psuedo standardized, but you could put your own link relation, there are just a few rules you should follow when identifying your own link relations. (See RFC5988 for details)