WS API is the way SonarQube can be integrated in various environments. It must:
- Have a very good documentation, auto-generated as much as possible to prevent desynchronization
- Have consistency across all the different WS in terms of naming, behaviour, error reporting, ...
- Have a clear deprecation strategy and stick to it
- it is highly used (even more since the scope of plugin development API has been reduced)
- it provides more and more facilities
- hard to find out what are the recent services to uses and the old ones (ex: api/components is rarely used compared to api/projects)
- some parameters have different names depending on the service you are using
- because of point 1- it is hard to understand / see the consistency in the naming of the parameters and the services
- retrieving information may requires many calls which could be for some simple operation a bit frustrating (should be reported by the support case by case)
- hard to understand why you should create, delete and list projects and views in api/project and api/views but that you should get it via api/component/show
- (doc) Write down the informal WebAPI convention you are following for new development: naming of services, usage of component key / ID, each service should have precise
- (doc) Ease / explain how to get keys or ids required for the queries
- (doc) Hide by default the deprecated parameters in WebAPI documentation
- Deprecate all legacy services & parameters that does not fulfill new WebAPI conventions
- Remove/replace technical database IDs from all parameters and responses (since they are not supposed to be used anymore)
- Replace paramater UUID, id by componentId and key by component
Personal suggestion, I would use explicit parameter names for ID and Key (issueId, metricId, groupID...). It is harder to read different queries with parameters 'id' that do not have the same meaning.
- api/ce/activity should have componentKey as parameter
- api/ce/task should have componentKey as parameter
- api/ce/task replace parameter 'id' per 'componentId' to be coherent regarding other api/ce
- Use the same parameter name for the renamed key in api/components/update_key and api/components/bulk_update_key (currently 'newKey' and 'to')
- api/custom_measures make a choice if you want to use id or metricId, there are inconsistencies in the different services
- api/custom_measures replace projectId by componentId and projectKey by componentKey
- api/duplications/show replace key and UUID by componentKey and componentId
- api/issues make a choice between id, issue, componentUuids
- api/issues/search lot of *UUID to turn into *id (componentUuids, fileUuids, moduleUuids, projectUuids)
- should api/issues/tags and api/issues/transitions be suffixed by '/list'?
- api/issues/assign parameter 'me' is badly deprecated
- api/project_links make a choice between id and project id, there are inconsistencies in the different services
- api/projects/index what is the purpose of 'views' parameter here?
- api/qualityprofiles/remove_project rename 'projectUuid' parameter