You should have internal docs to promote consistency among implementations

I think Sonar should think about having some internal documentation about API’s to ensure that developers do things consistently. (I mean internal to Sonar.) I first raised this thought in conjunction with thread Style tag applied inconsistently but it goes further than that.

For instance, there are a lot of cases in web_api where two functions will use different names for the exact same parameter. It appears that different developers went off in separate corners, each implementing their own function independently.

Here are a few examples:

  1. In api/issues/add_comment, the parameter containing the text of the comment being added is called “text” but in api/hotspots/add_comment the same thing is called “comment” – whereas in api/hotspots/edit_comment it’s “text” again, while “comment” means the key of the comment rather than its text.

  2. You request additional fields from api/issues/search with the “additionalFields” parameter, but it’s just “f” for api/rules/search.

  3. Some functions (e.g., api/qualityprofiles/deactivate_rules) require the unique quality profile key, while others (e.g., api/qualityprofiles/remove_user) require a combination of the language and the quality profile name (which is only unique within one language which is why the language key is required). Those two are essentially equivalent, if I understand correctlly, so it seems the functions should consistently use one or the other, or every function should allow both methods.

  4. For specifying date ranges, both names and formats are all over the place. Use “createdAfter” in api/issues/search, “since” in api/qualityprofiles/changelog, “available_since” in api/rules/search (which only takes dates and not a full timestamp)…

Parameters where you get it right: s, p, ps, q, asc, language…

1 Like
  1. The quality profile key is specified in api/qualityprofiles/deactivate_rules (plural) using the parameter name qprofile, but in api/qualityprofiles/deactivate_rule (singular), the same parameter is named ‘key’ (and also in api/qualityprofiles/activate_rule).