REST - Resource and Collection Representations

Question

I have a confusion with the design of collection resources. Let's say I have a user resource - represented as below.

http://www.example.com/users/{user-id}
user : {
  id : "",
  name : "",
  age : "",
  addresses : [
    {
      line1 : "",
      line2 : "",
      city : "",
      state : "",
      country : "",
      zip : ""
    }
  ]
}

Now, how should my users collection resource representation be? Should it be a list of user representations (as above)? Or can it be a subset of that like below:

http://www.example.com/users/
users : [
  {
    id : "",
    name : "",
    link : {
      rel : "self",
      href : "/users/{id}"
    }
  }
]

Should the collection resource representation include the complete representation of the containing resources or can it be a subset?

Answer 1

Media types define the rules on how you can convey information. Look at the specifications for Collection+JSON and HAL for examples of how to do what you are trying to do.