REST API eager or lazy?

Question

What is better? When a REST endpoint is queried for an entity - to return all the entities and sub-entities at once and then display them on the UI using some client side code (let's call it 'eager' mode), or it is better to return the main entity first and instead of its sub-entities, to return those sub-entities id's and then let the UI take care and issue the correct REST request for each id? (let's call it lazy mode).

So to return this JSON (this is actually not a valid JSON, just left the region: prefix for you to understand what entity it is):

country: {
 name: 'C1',
 regions: [
   region: {
      id: 'I1'
      name: 'R1',
      area: 'A1'
   },

   region: {
      id: 'I2'
      name: 'R2',
      area: 'A2'
   },
]

}

or this :

country: {
 name: 'C1',
 regions: ['I1','I2']
}

and then:

GET /rest/region/I1
GET /rest/region/I2

Which one is better? And when to use which? Thank you

Answer 1

Such a decision should usually be made based on need rather than trying to design everything up front. Think about who is using your service (you mention that it will be used from the UI) and what the requirements are.

Does the UI always need to load all of the data? If so, then lazy loading makes no sense at all and will just add complexity to your client side code. You can always implement 'lazy loading' at another URL later if you encounter performance issues or if you add another UI page that does not require all of the data.

If the UI by default only displays the 'top level data' and the more detailed information is only displayed conditionally based on some input from the user, then it would make sense to go for the 'lazy mode', as all of the data is not required all of the time.

In essence, write the UI code before you write the API. That will tell you which implementation makes more sense.

Answer 2

Well, it depends, doesn't it?

If the data is not going to change, you can go for eager loading.

If you are providing offline support, which means even when the user disconnects from the Internet you want your client to be working, eager loading is a must. It would need a well thought client side framework though.

If the data is frequently modified, it's better to do lazy loading.

If data is secured, then it's better to give it in small pieces rather than all at once but this is open to discussion.

In short, the rule of thumb is if your UI is smart and backend is dumb(er), go for eager loading, whereas if all the business logic lies on backend and UI is merely a representation, go for lazy loading.

Hybrid is not a bad idea either.