A documentation on Discussion API, "Create new commit thread" is severily flawed.
Problem to solve
Creates a new thread to a single project commit.
What in this case is meant by required(!) attributes Base commit SHA in the source branch , SHA referencing commit in target branch and SHA referencing HEAD of this commit?
I (likely, others as well) have no clue, what are "source branch" and "target branch" in respect to a single commit. And "HEAD of this commit" is not much clearer.
As well all descriptions related to "Discussions API / Commits" (https://docs.gitlab.com/ee/api/discussions.html#commits) use wrong resource /projects/:id/commits/:commit_id/discussions - the proper one is /projects/:id/repository/commits/:commit_id/discussions
- It isn't mentioned that unlike other API operations on commits this one doesn't support only full 40-char SHAs, but abbreviated SHA and other commitish .
Further details
Documentation may be found here https://docs.gitlab.com/ee/api/discussions.html#create-new-commit-thread
And here is its screenshot
It seems the text was blindly copy-pasted from the "Discussion API, Create new merge request thread" (which by itself not without problems - #35935 (closed) )
There is one more remark related to this API call - all other commit-related API operations use /projects/:id/repository/commits/:sha as their base path, e.g. POST /projects/:id/repository/commits/:sha/comments (see https://docs.gitlab.com/ee/api/commits.html#post-comment-to-commit), while discussion-related calls use /projects/:id/commits/:sha (/repository part is absent).
Below is an example of commands with their abbreviated output for the documented resource and the proper resource:
C:\tmp\glapi-testbed>curl --request GET --header "PRIVATE-TOKEN: ********************" https://main.gitlab.in.here.com/api/v4/projects/ce%2Fpublication-services%2Fnds%2Fpoc%2Fglapi-testbed/commits/081606577c73cdd236e37a5a77f471d1d1030cb0/discussions | python -m json.tool
{
"error": "404 Not Found"
}
C:\tmp\glapi-testbed>curl --request GET --header "PRIVATE-TOKEN: ********************" https://main.gitlab.in.here.com/api/v4/projects/ce%2Fpublication-services%2Fnds%2Fpoc%2Fglapi-testbed/repository/commits/081606577c73cdd236e37a5a77f471d1d1030cb0/discussions | python -m json.tool
[
{
"id": "da2f3dda655fdcdf0f7af1b320f6b699a9144bb5",
"individual_note": false,
"notes": [
...Here is an example of commands and their abbreviated output with full and abbreviated SHA-s along with, for comparison purposes, an output of "Commits API / Get a single commit" with an abbreviated SHA.
C:\tmp\glapi-testbed>curl --request GET --header "PRIVATE-TOKEN: ********************" https://main.gitlab.in.here.com/api/v4/projects/ce%2Fpublication-services%2Fnds%2Fpoc%2Fglapi-testbed/repository/commits/081606577c73cdd236e37a5a77f471d1d1030cb0/discussions | python -m json.tool
[
{
"id": "da2f3dda655fdcdf0f7af1b320f6b699a9144bb5",
"individual_note": false,
"notes": [
...
C:\tmp\glapi-testbed>curl --request GET --header "PRIVATE-TOKEN: ********************" https://main.gitlab.in.here.com/api/v4/projects/ce%2Fpublication-services%2Fnds%2Fpoc%2Fglapi-testbed/repository/commits/081606577/discussions | python -m json.tool
{
"message": "404 Commit Not Found"
}
C:\tmp\glapi-testbed>curl --request GET --header "PRIVATE-TOKEN: ********************" https://main.gitlab.in.here.com/api/v4/projects/ce%2Fpublication-services%2Fnds%2Fpoc%2Fglapi-testbed/repository/commits/081606577 | python -m json.tool
{
"author_email": "oleksandr.alesinskyy@here.com",
"author_name": "Oleksandr Alesinskyy",
"authored_date": "2019-10-25T15:35:40.000Z",
"committed_date": "2019-10-25T15:35:40.000Z",
"committer_email": "oleksandr.alesinskyy@here.com",
"committer_name": "Oleksandr Alesinskyy",
"created_at": "2019-10-25T15:35:40.000Z",
"id": "081606577c73cdd236e37a5a77f471d1d1030cb0",
...
...
Proposal
Fix ASAP