Make Gitlab API More Usable
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Problem to solve
The Gitlab API can be much easier for users to navigate. Currently, I need to go cross-reference several different pages to work with merge requests, for example: the Merge Request doc page, the Merge Request Approvals doc page, the Notes doc page, and so on. Additionally, the API requires me to construct URLs explicitly (ok, yes, templating exists to somewhat address this but it's fixing the symptom, not solving the problem). This in turn requires Gitlab to maintain N versions of the API, to prevent breaking users.
Intended users
This change will help those who work with the API -- developers working with CI/CD system integration.
User experience goal
The API should tell me what are additional valid, relevant URLs for the API resource I am looking at, and not require me to go find them on my own. For example, a merge request resource should give me fully-formed and valid links to the parent project resource, the related notes resource(s), the resource where I can perform the MR approvals, and so on. I should not have to go looking for them in physically separated documentation. Additionally, these URLs should not be dependent on an API version -- they should be valid for whatever version of the API I am using (which makes them backwards- and forwards-compatible). This decreases my workload significantly, and also frees up Gitlab to make changes, fixes and improvements to the API without fear of breaking anyone's existing code.
Proposal
HATEOAS. It's a thing, it's not new, and it works. Give me a HATEOAS API please. Stop making me construct URLs in my code! Make use of the HTTP method semantics, and give me various "rels" in the response body for my requests, so that I can just follow them.