Release API: Document allowed values for links' "filepath"
Problem to solve
I just ran into the following error "Validation failed: Links filepath is invalid". The documentation for the releases API does not explain which strings are valid:
- https://docs.gitlab.com/ee/user/project/releases/index.html#permanent-links-to-release-assets
- https://docs.gitlab.com/ee/api/releases/links.html
Further details
The first mistake was that the strings did not start with a forward slash ("/"). While the examples show this, it is not mentioned as a requirement. Then, I was using a ":" as part of the filepath, which, again, seems not to be allowed.
The only way I had to discover this was by trial and error and that is not very efficient.
Proposal
Specific requirements for the formatting of strings should be published as part of the docs. If they are being validated with a regex, please publish the said regex.
Ideally, a formal description of the API endpoint schema (e.g. using json-schema) would allow me to quickly and unambiguously understand the API.