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

That falls entirely on what you want it to do. The great thing about REST APIs is that they are so flexible. You can represent data in any way (theoretically) that you want.

Personally, I would have an attribute that allows the user to specify a subset or style of representation. For instance /users/{userid}.json?output=simple or /users/{userid}.json?subset=raw

Something along those lines would also allow you to nest representations and fine tune what you want without sacrificing flexibility:

/users/{userid}.json?output=simple&subset=raw

The sky is the limit

Answer 2

There isn't really a standard for this. You have options:

1. List of links

Return a list of links to the collection item resources (i.e., the user IDs).

http://www.example.com/users/
users : [
  "jsmith",
  "mjones",
  ...
]

Note that these can actually be interpreted as relative URIs, which somewhat supports the "all resources should be accessible by following URIs from the root URI" ideal.

http://www.example.com/users/ + jsmith = http://www.example.com/users/jsmith

2. List of partial resources

Return a list of partial resources (users), allowing the caller to specify which fields to include. You might also have a default selection of fields in case the user doesn't supply any - the default might even be "include all fields."

http://www.example.com/users/?field=id&field=name&field=link
users : [
  {
    id : "jsmith",
    name : "John Smith",
    link : "www.google.com"
  },
  ...
]

Answer 3

I would make the list service fine grained by entertaining the

http://www.example.com/users?include=address|profile|foo|bar

Any delimiter (other than & and URL encoded) like , or - can be used instead of |. On the server side, check for those include attributes and render the JSON response accordingly.

Answer 4

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.

Answer 5

It can be subset but depends on the data. take a look at the below code.

{
    "usersList": {
        "users": [{
            "firstName": "Venkatraman",
            "lastName": "Ramamoorthy",
            "age": 27,
            "address": {
                "streetAddress": "21 2nd Street",
                "city": "New York",
                "state": "NY",
                "postalCode": 10021
            },
            "phoneNumbers": [{
                "type": "mobile",
                "number": "[phone]"
            }, {
                "type": "fax",
                "number": "646 555-4567"
            }]
        }, {
            "firstName": "John",
            "lastName": "Smith",
            "age": 25,
            "address": {
                "streetAddress": "21 2nd Street",
                "city": "New York",
                "state": "NY",
                "postalCode": 10021
            },
            "phoneNumbers": [{
                "type": "home",
                "number": "212 555-1234"
            }, {
                "type": "fax",
                "number": "646 555-4567"
            }]
        }]
    }
}