diff options
Diffstat (limited to 'doc/api/notes.md')
| -rw-r--r-- | doc/api/notes.md | 173 |
1 files changed, 43 insertions, 130 deletions
diff --git a/doc/api/notes.md b/doc/api/notes.md index 572844b8b3f..388e6989df2 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -1,4 +1,4 @@ -# Notes +# Notes API Notes are comments on snippets, issues or merge requests. @@ -9,19 +9,19 @@ Notes are comments on snippets, issues or merge requests. Gets a list of all notes for a single issue. ``` -GET /projects/:id/issues/:issue_id/notes +GET /projects/:id/issues/:issue_iid/notes ``` Parameters: -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of an issue +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `issue_iid` (required) - The IID of an issue ```json [ { "id": 302, - "body": "Status changed to closed", + "body": "closed", "attachment": null, "author": { "id": 1, @@ -34,8 +34,6 @@ Parameters: "created_at": "2013-10-02T09:22:45Z", "updated_at": "2013-10-02T10:22:45Z", "system": true, - "upvote": false, - "downvote": false, "noteable_id": 377, "noteable_type": "Issue" }, @@ -54,8 +52,6 @@ Parameters: "created_at": "2013-10-02T09:56:03Z", "updated_at": "2013-10-02T09:56:03Z", "system": true, - "upvote": false, - "downvote": false, "noteable_id": 121, "noteable_type": "Issue" } @@ -67,13 +63,13 @@ Parameters: Returns a single note for a specific project issue ``` -GET /projects/:id/issues/:issue_id/notes/:note_id +GET /projects/:id/issues/:issue_iid/notes/:note_id ``` Parameters: -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of a project issue +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `issue_iid` (required) - The IID of a project issue - `note_id` (required) - The ID of an issue note ### Create new issue note @@ -82,13 +78,13 @@ Creates a new note to a single project issue. If you create a note where the bod only contains an Award Emoji, you'll receive this object back. ``` -POST /projects/:id/issues/:issue_id/notes +POST /projects/:id/issues/:issue_iid/notes ``` Parameters: -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of an issue +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `issue_id` (required) - The IID of an issue - `body` (required) - The content of a note - `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z @@ -97,61 +93,34 @@ Parameters: Modify existing note of an issue. ``` -PUT /projects/:id/issues/:issue_id/notes/:note_id +PUT /projects/:id/issues/:issue_iid/notes/:note_id ``` Parameters: -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of an issue +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `issue_iid` (required) - The IID of an issue - `note_id` (required) - The ID of a note - `body` (required) - The content of a note ### Delete an issue note -Deletes an existing note of an issue. On success, this API method returns 200 -and the deleted note. If the note does not exist, the API returns 404. +Deletes an existing note of an issue. ``` -DELETE /projects/:id/issues/:issue_id/notes/:note_id +DELETE /projects/:id/issues/:issue_iid/notes/:note_id ``` Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | -| `issue_id` | integer | yes | The ID of an issue | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `issue_iid` | integer | yes | The IID of an issue | | `note_id` | integer | yes | The ID of a note | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/11/notes/636 -``` - -Example Response: - -```json -{ - "id": 636, - "body": "This is a good idea.", - "attachment": null, - "author": { - "id": 1, - "username": "pipin", - "email": "admin@example.com", - "name": "Pip", - "state": "active", - "created_at": "2013-09-30T13:46:01Z", - "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon", - "web_url": "https://gitlab.example.com/u/pipin" - }, - "created_at": "2016-04-05T22:10:44.164Z", - "system": false, - "noteable_id": 11, - "noteable_type": "Issue", - "upvote": false, - "downvote": false -} +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636 ``` ## Snippets @@ -166,7 +135,7 @@ GET /projects/:id/snippets/:snippet_id/notes Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project snippet ### Get single snippet note @@ -179,7 +148,7 @@ GET /projects/:id/snippets/:snippet_id/notes/:note_id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project snippet - `note_id` (required) - The ID of an snippet note @@ -213,7 +182,7 @@ POST /projects/:id/snippets/:snippet_id/notes Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a snippet - `body` (required) - The content of a note @@ -227,15 +196,14 @@ PUT /projects/:id/snippets/:snippet_id/notes/:note_id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a snippet - `note_id` (required) - The ID of a note - `body` (required) - The content of a note ### Delete a snippet note -Deletes an existing note of a snippet. On success, this API method returns 200 -and the deleted note. If the note does not exist, the API returns 404. +Deletes an existing note of a snippet. ``` DELETE /projects/:id/snippets/:snippet_id/notes/:note_id @@ -245,38 +213,12 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `snippet_id` | integer | yes | The ID of a snippet | | `note_id` | integer | yes | The ID of a note | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/snippets/52/notes/1659 -``` - -Example Response: - -```json -{ - "id": 1659, - "body": "This is a good idea.", - "attachment": null, - "author": { - "id": 1, - "username": "pipin", - "email": "admin@example.com", - "name": "Pip", - "state": "active", - "created_at": "2013-09-30T13:46:01Z", - "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon", - "web_url": "https://gitlab.example.com/u/pipin" - }, - "created_at": "2016-04-06T16:51:53.239Z", - "system": false, - "noteable_id": 52, - "noteable_type": "Snippet", - "upvote": false, - "downvote": false -} +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659 ``` ## Merge Requests @@ -286,26 +228,26 @@ Example Response: Gets a list of all notes for a single merge request. ``` -GET /projects/:id/merge_requests/:merge_request_id/notes +GET /projects/:id/merge_requests/:merge_request_iid/notes ``` Parameters: -- `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of a project merge request +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `merge_request_iid` (required) - The IID of a project merge request ### Get single merge request note Returns a single note for a given merge request. ``` -GET /projects/:id/merge_requests/:merge_request_id/notes/:note_id +GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id ``` Parameters: -- `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of a project merge request +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `merge_request_iid` (required) - The IID of a project merge request - `note_id` (required) - The ID of a merge request note ```json @@ -324,8 +266,6 @@ Parameters: "created_at": "2013-10-02T08:57:14Z", "updated_at": "2013-10-02T08:57:14Z", "system": false, - "upvote": false, - "downvote": false, "noteable_id": 2, "noteable_type": "MergeRequest" } @@ -338,13 +278,13 @@ If you create a note where the body only contains an Award Emoji, you'll receive this object back. ``` -POST /projects/:id/merge_requests/:merge_request_id/notes +POST /projects/:id/merge_requests/:merge_request_iid/notes ``` Parameters: -- `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of a merge request +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `merge_request_iid` (required) - The IID of a merge request - `body` (required) - The content of a note ### Modify existing merge request note @@ -352,59 +292,32 @@ Parameters: Modify existing note of a merge request. ``` -PUT /projects/:id/merge_requests/:merge_request_id/notes/:note_id +PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id ``` Parameters: -- `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of a merge request +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `merge_request_iid` (required) - The IID of a merge request - `note_id` (required) - The ID of a note - `body` (required) - The content of a note ### Delete a merge request note -Deletes an existing note of a merge request. On success, this API method returns -200 and the deleted note. If the note does not exist, the API returns 404. +Deletes an existing note of a merge request. ``` -DELETE /projects/:id/merge_requests/:merge_request_id/notes/:note_id +DELETE /projects/:id/merge_requests/:merge_request_iid/notes/:note_id ``` Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | -| `merge_request_id` | integer | yes | The ID of a merge request | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `merge_request_iid` | integer | yes | The IID of a merge request | | `note_id` | integer | yes | The ID of a note | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/merge_requests/7/notes/1602 -``` - -Example Response: - -```json -{ - "id": 1602, - "body": "This is a good idea.", - "attachment": null, - "author": { - "id": 1, - "username": "pipin", - "email": "admin@example.com", - "name": "Pip", - "state": "active", - "created_at": "2013-09-30T13:46:01Z", - "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon", - "web_url": "https://gitlab.example.com/u/pipin" - }, - "created_at": "2016-04-05T22:11:59.923Z", - "system": false, - "noteable_id": 7, - "noteable_type": "MergeRequest", - "upvote": false, - "downvote": false -} +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602 ``` |