Uploaded image for project: 'Product Roadmaps'
  1. Product Roadmaps
  2. MMF-706

High quality of the WS API

    XMLWordPrintable

    Details

    • Type: EPIC
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Labels:
    • Epic Name:
      WS API Quality

      Description

      Context

      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

      Feedback from Support

      Good points
      • it is highly used (even more since the scope of plugin development API has been reduced)
      • it provides more and more facilities
      Some points to work on
      1. 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)
      2. some parameters have different names depending on the service you are using
      3. because of point 1- it is hard to understand / see the consistency in the naming of the parameters and the services
      4. 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)
      5. 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
      Here are some concrete inputs / suggestions for each previous point:
      • (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.

      Inconsistencies in SonarQube WebAPI 6.1-RC2
      • 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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              christophe.levis Christophe Levis
              Reporter:
              fabrice.bellingard Fabrice Bellingard
              Votes:
              1 Vote for this issue
              Watchers:
              4 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: