Rest : Return Complex Nested Data Vs. Multiple Calls

I have a REST api served by NodeJS to an AngularJS fronts. I work with users : GET /api/users #Returns all users POST /api/users #Create new user GET /api/users/:id #Retur

Solution 1:

Your question basically boils down to:

Which is better, one big HTTP request, or many small ones?

One thing to keep in mind is the expected network latency (ping time) between your clients and your server. In a high-latency situation with otherwise good bandwidth, many small requests will perform significantly worse than one large one.

Also, having one big request gives you better efficiency for compressing the response, and avoids the overhead of the extra HTTP requests and response headers.

Having said all that, I would still advise you to start with option 1, solely because you stated it is very easy for you to code. And then see if it meets your requirements. If not, then try option 2.

And as a final note, I generally prefer one big request to many small requests because that makes it easy to define each request as a transaction which is either completely applied or rolled back. That way my clients do not run into a state where some of their many small requests succeeded while others failed and they now have an inconsistent local copy of the data my API supplied.

Solution 2:

Come on, how much would it cost in performance, based on the thesis that the result will be almost the same, multiple requests vs one massive request. We're in 2016 and unless you're dealing with poor internet connections, you should do it by making multiple requests.

You're developing your app for 99% of the population of the globe or for the 1% part which uses Opera ( for the turbo feature )?

Also, if we are talking about designing a REST api, being consistent is probably the main idea of such kind of API. In your case, if you write the second method you'll have to write something similar into the rest of your code to keep consistency of all controllers, which can't be done.

Also, an API is an API and should not be modified when a front end application is being built on that API. Think at the situation when you have 10 apps that are requesting your API, but you're in the same situation you presented, but you need a different response for each. You're going to add new methods to the API ? That's a bad practice

Routing in a REST api should be done accordingly to the logical resources you have ( objects that can be manipulated with HTTP verbs ) :

Examples:

 * when you have a relation between entities

     /users/3/accounts       // should return a list of accounts from user 3
     /users/3/accounts/2     // should return account 2 from user 3

 * custom actions on your logical resources

    /users/3/approve
    /accounts/2/disable

Also a good API should be able to offer partial requests ( for example adding some querystrings parameters to an usual request : users/3?fields=Name,FirstName ), versioning, documentation ( apiDocs.js is very userful in this case ), same request type ( json ), pagination, token auth and compression ( I've never done the last one :) )

Solution 3:

I recommend modifying your endpoint for serving user resources to accept (through a query parameter) what associated resources should be included as a part of the respose:

/api/users?includes=groups&includes=constraints

This is a very flexible solution and if your requirement expands in future, you can easily support more associated resources.

If you concerned about how to structure the response, I recommend taking a look at JSON:API.

An advantage of using JSON:API is that if multiple users share same groups/constraints then you will not have to fetch multiple representations of the same entity.

Solution 4:

You're asking

which is better...

and that's not acceptable according to SO rules, so I will assume your question lies around what is REST supposed to do in certain cases.

REST is based on resources, which, in their own, are like objects with their own data and "accessors/getters".

When you're asking for /api/users/:id/groups, you're telling that you want to access, from the users resource/table, a specific user with an id and, from that user, the list of groups he/she belongs to (or owns, or whatever interpretation you want). In any case, the query is very specific for this groups resource (which, in REST terms, is unique, because every resource is universally directionable through its URL) and should not "collision" or be misinterpreted with another resource. If more than one object could be targeted with the URL (for example, if you call just /api/groups), then your resource is an array.

Taking that in consideration, I would consider (and recommend) always returning the biggest selection that matches the use case that you specify. For example, if I would create that API, I would probably do:

/users list of all users

/users/:id a specific user

/users/:id/groups groups to which the specific user has joined

/users/groups list of all groups that has at least one user

/users/groups/:id description of a particular group from /users/groups (detail)

etc...

Every user case should be completely defined by the URL. If not, then your REST specification is probably (and I'm almost sure) wrong.

==========

So, answering your question, considering that description, I would say your answer is: it depends what you need to do.

If you want to show every single constraint in the main page (possible, but not too elegant/crap UI), then yes, the first approach is fine (hope your end users don't kill you).

If you want to only ask for resources on demand (for example, when popping up info on mouse hover or after going to a specific section in the admin site), then your solution is something like the second one (yes, that's a big one... only if you really need that resource, you should use it).

Have you considered the path /api/users/:id/constraints on demand?

BTW, withConstraintsAndGroups is not a REST resource. REST resources are nouns (constraints or groups, but not both). Not verbs or adjectives.

Solution 5:

I doesnt seem to me that for the admin page performance is too much of an issue. The only difference between the pretty much is, that in #1 you have 3 api calls, with #2 only one. The data should be the same, the data should be reasonable, not extremely huge. So if #1 is easier to code and maintain you should go with that. You should not have any performance issues.