REST - Resource and Collection Representations

问题:

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?

回答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.

回答2:

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

回答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.

回答4:

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"
  },
  ...
]

回答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"
            }]
        }]
    }
}