API - Multiple requests vs separating user roles

Question

I'm working on the frontend of a single page application and I have to list a number of students. Each student is attached to a certain user_id This is what the API returns for all user roles (superadmin, admin, professor, student) when I perform GET /students:

{
  address: null
  class_id: 184
  class_name: "I B"
  date_of_birth: null
  first_name: "first"
  gender: null
  grade: 1
  id: 192
  last_name: "last"
  nationality: null
  place_of_birth: null
  ranking_by_class: 0
  ranking_by_school: 0
  registration_number: null
  user_id: 238
}

I'm working on the superadmin role at the moment where I'm in need of extra data from each student (subscription_type), which is only available on GET /users/:id

So when I'm listing 20-30 students on a page via GET /students/, in order to get the subscription_type, I'll also need to do 20-30 extra requests, one for each student.

I talked to the API guy about this and I was told that including the extra data into students "is not the RESTful way of doing it", "it will slow down the response times even more" and that "30 extra requests weigh less than a big chunk".

I don't know anything about working on an API, so I can't really have a say, but am I crazy to think that 30 requests on a page load is ludicrous?

So what next? Do I go ahead and perform the extra requests? Should he separate the responses for each user role and include just the things I need for each role? What is the correct way of handling this?

Answer 1

While strictly speaking the API guy is correct, following the RESTful gospel too strictly can lead to inefficiencies like the 1+N problem created by the purist implementation. A key concept in RESTful design is that resources do not have to map directly to domain objects. When designing resources one must look at the usage scenarios. In the super admin scenario, it sounds like when the client requests a collection of students and it also typically or always needs data from users, specifically subscription_type. The object model is clearly normalized as it should be, but that does not say that the resources must be, or must always be.

There are a couple of different patterns I have used to make similar scenarios more efficient. Which (if either) apply depends on how the resources are consumed by clients.

Composite Resource

This is the combination of all or part two or more domain objects (e.g. student and user) into a single resource.

Since all students are presumably also users, you could include all or part of the user data in the student resource as appropriate.

GET /students

{
  address: null
  class_id: 184
  class_name: "I B"
  date_of_birth: null
  first_name: "first"
  gender: null
  grade: 1
  id: 192
  last_name: "last"
  nationality: null
  place_of_birth: null
  ranking_by_class: 0
  ranking_by_school: 0
  registration_number: null
  user_id: 238
  subscription_type: "foo"
}

Related Resources

(Similar to another response) This is a technique where the client can indicate that it wants a related resource included in the response. This is particularly useful in "has a" type relationship in the domain model. It allows the client to essentially lazy load or eager load the resource.

GET /students

{
  address: null
  class_id: 184
  class_name: "I B"
  date_of_birth: null
  first_name: "first"
  gender: null
  grade: 1
  id: 192
  last_name: "last"
  nationality: null
  place_of_birth: null
  ranking_by_class: 0
  ranking_by_school: 0
  registration_number: null
  user_id: 238
}

GET /students?include_user=true

{
  address: null
  class_id: 184
  class_name: "I B"
  date_of_birth: null
  first_name: "first"
  gender: null
  grade: 1
  id: 192
  last_name: "last"
  nationality: null
  place_of_birth: null
  ranking_by_class: 0
  ranking_by_school: 0
  registration_number: null
  user_id: 238
  user:
  {
   id: 238
   subscription_type: "foo"
   ...
  }
}