Designing REST API(s), more complicated objects or more requests? - rest

Question

I have problem with REST API(s) for front-end GUI and am wondering which approach is better. Are there any design patterns for these types of problems?
uri: /users/list
response: [
{
id: "1",
name "Aaa",
surname "Bbb",
contactDetails: {
telephone: "111-111-111"
email: "mail#mail.pl"
}
},
...
]
OR
uri: /users/list
response: [
{
id: "1",
name "Aaa",
surname "Bbb"
},
...
]
uri: /emails/list?userIds=1,..
response: [
{
userId: "1",
email: "mail#mail.pl"
}
]
uri: /telephones/list?userIds=1,..
response: [
{
userId: "1",
telephone: "111-111-111"
}
]
and it's the same for a single user:
uri : users/{id}
uri : users/{id}/emails
uri : users/{id}/telephones
============== Extended class model =================================
Below I paste JSON classes designed for question needs.
SystemPart : {
id : "sp2",
name : "UserAdministration",
parentSystemPart : {
id : "sp1",
name : "Administration",
...
}
...
}
SystemPermission : {
permissionType : "MODERATOR",
systemParts : [ // list of SystemPart
{
id : "sp1",
name : "UserAdministration",
parentSystemPart:{...}
},
...
],
...
}
User: {
id : "u1",
name : "a",
surname : "b",
contactDetails : {
telephone : "111-111-111"
email : "mail#mail.com"
},
identityCard : {
idType : "Id",
number : "321"
}
systemPermissions : [ // list of SystemPermission
{
permissionType : "MODERATOR",
systemParts : [...]
},
...
]
}
MapPoint : {
id : "mp1",
x : 11.11,
y : 22.22,
createdBy : { // User
id : "u1",
...
systemPermission : [...]
}
}
GUI client would like to show map point data with only it's author name, and surname
and now api for list of MapPoints
/map-points/list?x=11.00&y=22.00&d=5.0
other part of GUI would like to get list of users with its permissions
/users/list?page=0&size=5
In my opinion problem is in map-points list api which JSON is to big

Answer 1

I'd go with the first approach. The User class is pretty small and I don't see any benefits to calling the service separately for contact details.
Ensure that the client can filter the results based on every parameter, that way it is easy for the user of your API to get exactly what he/she wants.
For e.g. /users/list will get back everything which is perfect if there are relatively small number of users in the list and it's better to eagerly cache them all to improve client's performance.
uri: /users/list
response: [
{
id: "1",
name "Aaa",
surname "Bbb",
contactDetails: {
telephone: "111-111-111"
email: "mail#mail.pl"
}
},
...
]
If the number of users are significantly large, make sure the list can be filtered down to a small quantity based on every(or at least the significant ones like last name) parameter and the client can call your service for specific users and lazily load them as and when needed.
uri: /users/list?surname=Bbb
or
uri: /users/list?id=1
should get back:
response: [
{
id: "1",
name "Aaa",
surname "Bbb",
contactDetails: {
telephone: "111-111-111"
email: "mail#mail.pl"
}
}
]