How detailed should API responses be?


I would like to define rules that describe how detailed an API response should be.


To save you the effort of reading: It is of course also possible to keep the whole thing in the API documentation, but I am asking for an exact rule / best practise.

And by the way, I am not using ORM tools, I write plain SQL.


Let’s say there are the resources user and group. Users can have multiple groups and groups can have multiple users. When asking for a User by ID, would you also return the groups he is in? Would this group array only contain the IDs or contain detailed group objects?

If the group objects were detailed, there would be a risk that they would again contain user objects (cycles => users have groups which have users…). It is also possible that some nested objects are relevant and others are not. Some nested objects may need to be provided.

If you ask for a user, the database will only return the user. If the group should be supplied as an attribute, the query would have to be extended.

I am now also thinking of the extensibility of the API. When do I only return the user, when do I return a user with all its groups? I want to keep the API structure clean. Given these example routes

  • /users => return all users

  • /users/:id => return one user by user id

how would you decide which nested objects should be returned?

If you want to generalize the whole thing now, are there fixed rules?