API Enhancement: List all, including nested, subgroups

Problem to solve

The /groups/<grp>/projects endpoint accepts the query parameter include_subgroups=true to include all projects under the group in the list, even those nested under other subgroups. There is no similar ability for /groups/<grp>/subgroups, however. There are only two available workarounds: 1. walk the group tree; 2. list all groups on gitlab and filter out those not nested under the desired group. The /groups/<grp>/subgroups endpoint should accept include_subgroups=true as well, to reduce API load under these circumstances.

We are running several processes that are interested in exploring the list of all subgroups belonging to our top-level group. We have tried both work-around approaches described above, and in our case, the fastest way to get the desired information is to actually list all groups and filter out the non-relevant ones.

Intended users

This enhancement benefits Sasha, who is trying to interact with the gitlab API to retrieve the list of all groups belonging to her organization.

User experience goal

The user should not have to explore the full tree to get the list of subgroups (lots of API calls), nor should they have to list all groups accessible via gitlab and filter out the non-relevant ones.

Proposal

Add include_subgroups=true to the API for subgroups of groups.

Permissions and Security

The permissions model is not changed by this request; this is merely consolidating all the data that would be retrieved by walking the group tree into a single call.

Documentation

[1] documents the include_subgroups parameter for listing projects. The desire is to add a similar parameter for [2].