Download a (sub-)folder from a repository via the Repositories API

Problem to solve

Via the Repositories API it's currently only possible to download the entire repository as a zip file. In some situations, however, it may be desirable to download just a portion (folder) of the repository as a zip file.

gitlab-ce#24704 raised a similar feature request for the Gitlab UI, which was inplemented with MRs gitlab-ce!26532 and gitlab-ce!27275.

Intended users

Developers and other API users (e.g. installing a package from source).

Further details

At the very least, it keeps the functionality of the UI and the API in sync.

Proposal

If I understand the logic behind the Repositories API correctly, GET /projects/:id/repository/archive[.format] would have to support a path parameter for this. If the path parameter is empty or not given, archive[.format] contains the whole repo.

Permissions and Security

Permissions should be the same as with the Repositories API, (or the Repository files API, which has the read_repository scope, which the Repositories API has not, see #28324).

Documentation

Add path parameter to Get file archive.

Update: @porsager suggested to support multiple paths (repo sub-folders) below. I would leave it to the one implementing this feature to decide whether this is desirable/doable. Maybe it is best to start out with a single path/folder?

Testing

I don't know, but I would expect similar tests as for the existing Get file archive functionality.

What does success look like, and how can we measure that?

It is possible to get a file archive with only the contents of a (sub-)folder of the repository via the API.

Links / references

Following up on @patrickbajao's suggestion, /cc-ing @DouweM @jramsay like he did.