RESTful design: resolving relationships - api

Question

My questions are based on this article: should-restful-apis-include-relationships
Let's say I have the following resources: users and roles
A single user can be retrieved by api/users/{userId} and a single role by api/roles/{roleId}
The response data of a single user looks like this:
Id: 1
Firstname: Alice
Lastname: Henderson
Email: alice#henderson.com
Roles: api/users/1/roles
To get the roles of this user the application needs to call the returned url api/users/1/roles
For displaying 1 user this approach seems to be ok. But if I want to display all users with their corresponding roles the application needs 1 call to api/users and x calls to api/users/x/roles
How can this design be improved for retrieving multiple users and resolving their role relationships?

Answer 1

You can design your API to accept one or more query parameters which specify the detail level you desire. For instance:
GET /api/users/1?expand=role(self, id, name)
{
"id": 1
"firstName": "Alice"
"lastName": "Henderson"
"email": "alice#henderson.com"
"roles": [
{
"self": "api/roles/4"
"id": 4
"name": "Administrator"
},
{
"self": "api/roles/7"
"id": 7
"name": "Uberuser"
}
]
}