Let's say I have a REST API with resources that look something like this:
/users/<id>
{
"id": <str:user_id>,
"firstName": <str:first_name>,
"lastName": <str:last_name>,
"favoriteColor": <str:color_name>,
"lotsOfStuff": {...}
}
/groups/<id>
{
"id": <str:group_id>,
"name": <str:group_name>,
"members": <array:list_of_users>
}
I'm wondering what counts as an acceptable way to populate the group.members array. Most things I read imply that the options are:
- include only id's (or links) that reference each user in the group. Something like:
members: ["/users/1", "/users/2", "/users/3"]
- include a full copy of the user resource.
members: [
{
"id": "1",
"firstName": "Jon",
"lastName": "Doe",
"favoriteColor": "Blue",
"lotsOfStuff": {...}
},
...
]
Option 1 can be very inconvenient for the client because it requires a lot of extra requests to learn about the group members.
Option 2 might be inefficient or infeasible if the user resource is very large.
The 3rd option I would like to use is to include a reference plus a small subset of the target resource. Something like:
"members": [
{
"id": "users/1",
"name": "Bob"
},
{
"id": "users/2",
"name": "Sally"
}
]
Now the client has something to work with, but can make an extra call for details. This maps nicely onto list-details UIs.
Is this considered bad practice? Is there a terrible pitfall here that I'm missing?
