Trying to get my head around the Sonarcloud API but the documentation is HUGELY incorrect & missing so much!
Parameters for some endpoints are missing or marked as optional when they’re not and required params are completely missing. This is not what I would come to expect for a paid service!
Web API (sonarcloud.io)
Is this link the only documentation you have and if so when is this going to be updated ?
An example would be the api/duplications - params do not show any required in the documentation but if you try and call the api you get this response:
"msg": "Either 'uuid' or 'key' must be provided"
With no explanation of the terminology used. What is the UUID? What is a component?
Could you advise on where this is in your road map and when it’s likely to be fixed?
The web api documentation is provided in case it’s useful, but it’s not even considered a secondary deliverable. I don’t believe significant updates are currently in the roadmap. I’m sorry it’s been frustrating, rather than useful for you.
Generally, the best way to master the API is to perform the desired action via the UI and eavesdrop to see which calls the UI made to accomplish the action.
To answer your questions, a UUID is a universally unique id. A component is a unit of a project (recursive). So, as described here in the web API docs, it is a: file, directory, project, …
I just found this issue after battling with the API docs for a while. Another example I found was /api/issues/search which has no required parameters at all unless you try and use it. Then the error is “At least one of the following parameters must be specified: projects, projectKeys (deprecated), componentKeys, assignees, issues”. Some of these are not even defined as parameters.
Let me just make a clear (and obvious) statement: the web api documentation are very useful for anyone wanting to use the APIs!
The poor quality of them affects paying and free customers for SonarCloud and SonarQube. Will you prioritise improving the docs and APIs themselves (e.g using consistent paging responses) if enough customers ask you to?
To avoid others wasting as much time as I have, a simple improvement would be to put a massive caveat at the top of the API docs explaining that they are not a reliable source of information and proposing your alternative approach.