Docs - product feedback: GitHub Rest API: Returns very annoying (useless and misleading) error messages
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Hello
We have already programmed with the GitHub REST API and it works very well and satisfactorily. Unfortunately, we don't like Microsoft and therefore wanted to switch to GitLab...
But programming with the GitLab REST API is very frustrating because it is poorly documented, even after years it is not finished at all and therefore, we have to look for workarounds all the time and the error messages are extremely tedious:
Do you ask about the not complete API and the Workarounds? It took us just about 15 minutes to find the first problem:
- Of course, it is possible to retrieve all projects of a user: https://gitlab.com/api/v4/users//projects
- But it is impossible to retrieve all groups of a user. Others have complained about this problem a long time ago.
The problem with REST API error messages This problem is also quite embarrassing because the REST API was obviously badly programmed. Two examples:
- If one calls a REST API Function that is not available on the called Server (because e.g. it's only available on-premise), then the REST API does not return "Function not available" but something stupid like "user not found" which is not the real issue!
- If one uses e.g. this API: GET /projects/:id/repository/files/:file_path and there is an issue, then it returns "404 Commit Not Found" which does not help at all. Of course, the question is: What was not found? Is it an authentication issue? Is the project Id invalid? Did the user had a typo and wrote "repostory" instead of "repository"? Or is the File_Path invalid?
The Proposal is pretty simple and very common for decades: If something fails in the REST API, then the failing logic/part must report an explaining error.
- The authentication did not work? Then the user receives an error message that the username/password is probably incorrect.
- A REST API function is called that the server does not know? Then the user receives the error message that the function is unknown.
- A Commmit-, User-, File-, …ID is unknown? Then the User gets the message that the Commmit-, User-, File-, …ID is invalid.
- Does any part of the URI have a typo? Then the user receives the information for which part of the URI the REST API cannot do anything.
I'm sure you recognize the pattern:
A software module, function, … detects an error - and this item then also reports what the error is because it knows the reason
Today, almost every project we do uses automation (we have around 700 employees and therefore have somewhat larger projects) and then a great, clear, complete and documented REST API is quite central.
Today, almost every project we do uses automation (we have around 700 employees and therefore have somewhat larger projects) and then a great (usable), clear, complete and fully documented REST API is quite central.
If one already stumbles over the first problems and questions after 20 or 30 minutes, then our projects are at risk and we have to stay with providers who have a complete REST API.
Please excuse my angry tone, because actually, I love GitLab. But I am frustrated that after years I still can't implement GitLab in our company.