Addons-server: rename POST param for submitting a canned response comment

[kumar303]

User story:

As an add-on reviewer, I want to submit a canned response comment to make review communication more consistent and efficient

The API for this landed in https://github.com/mozilla/addons-server/issues/11807 and the POST endpoint is documented at https://addons-server.readthedocs.io/en/latest/topics/api/reviewers.html#post--api-v4-reviewers-addon-(int-addon_id)-versions-(int-version_id)-draft_comments-

The POST parameter draft_comment.id should be renamed to canned_response_id or something like that to convey that it links to an existing canned response object.

[ioanarusiczki]

@kumar303

• if I POST with canned_response which has one of the id's listed by https://addons-dev.allizom.org/api/v4/reviewers/canned-responses/
  I receive a 201 status and the canned_response object is detailed in the response such as:
  "canned_response": {
  "id": 92,
  "title": "JavaScript library hash doesn't match",
  "response": "Your add-on includes an JavaScript library file that doesn't match our checksums for known release versions. We require all add-ons to use unmodified release versions, obtained directly from the developer's website. You can find a list of the library versions we support here: http://mzl.la/amo-libs",
  "category": "Development Practices"

To make the docs more clear for POST my suggestion would be to replace:
canned_response (int) – The id of the draft comment (optional).
to:
canned_response (int) – The id of the canned response (if a comment is not available).

PATCH should be updated into canned_response (int) – The id of the canned response (optional).

• I also tried with `canned_response_id" or "canned_response_id_id_id":"" and the POST can be completed with a 201 status but the object is "canned_response": null, and in the same response I receive "comment": " " PATCH returns a 200 but the response shows the previous canned_response id (if it was set). This means that if I don't use the correct parameter format specified by the docs the examples given won't return an error, they're just being ignored.

[kumar303]

Thanks, I filed https://github.com/mozilla/addons-server/issues/12263 to improve the docs

I also tried with `canned_response_id" or "canned_response_id_id_id":"" ... This means that if I don't use the correct parameter format specified by the docs the examples given won't return an error, they're just being ignored.

Yeah, this is confusing. Unfortunately this is an intentional design choice for the API. The main argument for this behavior IIRC is that it makes it easy to phase out old parameters without breaking clients. That's not such a strong case IMO.