REST - Resource and Collection Views

Question

I have a confusion with the design of collectible resources. Let's say I have a user resource below.

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

Now, what should be the presentation of a user collection resource? Should it be a list of user views (as above)? Or it could be a subset of the following:

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

Should a collection resource representation include a complete representation of the contained resources, or maybe a subset?

Answer 1

Types of media files determine the rules for transmitting information. Look at the characteristics of Collection + JSON and HAL for examples of how to do what you are trying to do.

Answer 2

It totally depends on what you want. The great thing about the REST API is that they are so flexible. You can represent the data in any way (theoretically) that you want.

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

Something along these lines will also allow you to embed views and fine-tune what you want without sacrificing flexibility:

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

Heaven is the limit

Answer 3

There is no standard for this. You have options:

1. List of links

Returns a list of links to the resources of collection items (for example, user identifiers).

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

Note that in fact they can be interpreted as relative URIs, which somewhat supports "all resources must be accessible following URIs from the root URI".

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

2. List of partial resources

Returns a list of partial resources (users), allowing the caller to specify which fields to include. You can also have a default selection of fields in case the user does not provide any data - by default it can 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 4

I would make the list service fine-grained, entertaining

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

Instead of | You can use any delimiter (except encoding and URL), for example , or - . On the server side, check for include attributes and process the JSON response accordingly.

Answer 5

It may be a subset, but it depends on the data. take a look at the code below.

 { "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" }] }] } }