diff options
author | Z.J. van de Weg <zegerjan@gitlab.com> | 2016-06-17 22:03:57 +0200 |
---|---|---|
committer | Z.J. van de Weg <zegerjan@gitlab.com> | 2016-06-17 22:03:57 +0200 |
commit | e0bdcd2f2fd96194f8d9121c5b912143012b616c (patch) | |
tree | 39f6312673bf648477443aed525e45bdcb9eff85 /doc/api/award_emoji.md | |
parent | 05a4a586b5e80f7d30de51199d5bb5bcf7f61705 (diff) | |
download | gitlab-ce-e0bdcd2f2fd96194f8d9121c5b912143012b616c.tar.gz |
fixup! updated docs for api endpoint award emoji
Diffstat (limited to 'doc/api/award_emoji.md')
-rw-r--r-- | doc/api/award_emoji.md | 199 |
1 files changed, 181 insertions, 18 deletions
diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index ecabc5dc7b8..b44f8cfd628 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.md @@ -1,12 +1,14 @@ # Award Emoji + >**Note:** This feature was introduced in GitLab 8.9 + An awarded emoji tells a thousand words, and can be awarded on issues, merge requests and notes/comments. Issues, merge requests and notes are further called `awardables`. -## Issues and MergeRequests +## Issues and merge requests -### List an awardables emoji awards +### List an awardable's award emoji Gets a list of all award emoji @@ -23,7 +25,7 @@ Parameters: | `awardable_id` | integer | yes | The ID of an awardable | ```bash -curl -X GET -H "PRIVATE-TOKEN: ir6jesYP_Am5DPy7d1y7" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji ``` Example Response: @@ -39,7 +41,7 @@ Example Response: "id": 1, "state": "active", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "web_url": "http://localhost:3000/u/root" + "web_url": "http://gitlab.example.com/u/root" }, "created_at": "2016-06-15T10:09:34.206Z", "updated_at": "2016-06-15T10:09:34.206Z", @@ -55,7 +57,7 @@ Example Response: "id": 26, "state": "active", "avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80&d=identicon", - "web_url": "http://localhost:3000/u/user4" + "web_url": "http://gitlab.example.com/u/user4" }, "created_at": "2016-06-15T10:09:34.177Z", "updated_at": "2016-06-15T10:09:34.177Z", @@ -83,7 +85,7 @@ Parameters: | `award_id` | integer | yes | The ID of the award emoji | ```bash -curl -X GET -H "PRIVATE-TOKEN: ir6jesYP_Am5DPy7d1y7" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/1 +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/1 ``` Example Response: @@ -98,7 +100,7 @@ Example Response: "id": 26, "state": "active", "avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80&d=identicon", - "web_url": "http://localhost:3000/u/user4" + "web_url": "http://gitlab.example.com/u/user4" }, "created_at": "2016-06-15T10:09:34.177Z", "updated_at": "2016-06-15T10:09:34.177Z", @@ -125,7 +127,7 @@ Parameters: | `name` | string | yes | The name of the emoji, without colons | ```bash -curl -X POST -H "PRIVATE-TOKEN: ir6jesYP_Am5DPy7d1y7" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji?name=blowfish +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji?name=blowfish ``` Example Response: @@ -140,7 +142,7 @@ Example Response: "id": 1, "state": "active", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "web_url": "http://localhost:3000/u/root" + "web_url": "http://gitlab.example.com/u/root" }, "created_at": "2016-06-17T17:47:29.266Z", "updated_at": "2016-06-17T17:47:29.266Z", @@ -168,7 +170,7 @@ Parameters: | `award_id` | integer | yes | The ID of a award_emoji | ```bash -curl -X DELETE -H "PRIVATE-TOKEN: ir6jesYP_Am5DPy7d1y7" http://localhost:3000/api/v3/projects/1/issues/80/award_emoji/344 +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/344 ``` Example Response: @@ -183,7 +185,7 @@ Example Response: "id": 1, "state": "active", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "web_url": "http://localhost:3000/u/root" + "web_url": "http://gitlab.example.com/u/root" }, "created_at": "2016-06-17T17:47:29.266Z", "updated_at": "2016-06-17T17:47:29.266Z", @@ -194,11 +196,172 @@ Example Response: ## Award Emoji on Notes -The end points mentioned above are available for notes too. Notes are a sub -resource of both Issues and MergeRequests. The endpoints changes, for example, -to receive all awards on an issue the endpoint would be: -`/projects/:id/issues/:issue_id/award_emoji`, for the note it would be: -`/projects/:id/issues/:issue_id/notes/:note_id/award_emoji`. Thus after the -resource you'd add `notes/:note_id`. +The endpoints documented above are available for Notes as well. Notes +are a sub-resource of Issues and Merge Requests. The examples below +describe working with Award Emoji on notes for an Issue, but can be +easily adapted for notes on a Merge Request. + +### List a note's award emoji + +``` +GET /projects/:id/issues/:issue_id/notes/:note_id/award_emoji +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `issue_id` | integer | yes | The ID of an issue | +| `note_id` | integer | yes | The ID of an note | + + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/notes/1/award_emoji +``` + +Example Response: + +```json +[ + { + "id": 2, + "name": "mood_bubble_lightning", + "user": { + "name": "User 4", + "username": "user4", + "id": 26, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80&d=identicon", + "web_url": "http://gitlab.example.com/u/user4" + }, + "created_at": "2016-06-15T10:09:34.197Z", + "updated_at": "2016-06-15T10:09:34.197Z", + "awardable_id": 1, + "awardable_type": "Note" + } +] +``` + +### Get single note's award emoji + +``` +GET /projects/:id/issues/:issue_id/notes/:note_id/award_emoji/:award_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `issue_id` | integer | yes | The ID of an issue | +| `note_id` | integer | yes | The ID of a note | +| `award_id` | integer | yes | The ID of the award emoji | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/notes/1/award_emoji/2 +``` + +Example Response: + +```json +{ + "id": 2, + "name": "mood_bubble_lightning", + "user": { + "name": "User 4", + "username": "user4", + "id": 26, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80&d=identicon", + "web_url": "http://gitlab.example.com/u/user4" + }, + "created_at": "2016-06-15T10:09:34.197Z", + "updated_at": "2016-06-15T10:09:34.197Z", + "awardable_id": 1, + "awardable_type": "Note" +} +``` + +### Award a new emoji on a note + +``` +POST /projects/:id/issues/:issue_id/notes/:note_id/award_emoji +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `issue_id` | integer | yes | The ID of an issue | +| `note_id` | integer | yes | The ID of a note | +| `name` | string | yes | The name of the emoji, without colons | + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/notes/1/award_emoji?name=rocket +``` + +Example Response: + +```json +{ + "id": 345, + "name": "rocket", + "user": { + "name": "Administrator", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.example.com/u/root" + }, + "created_at": "2016-06-17T19:59:55.888Z", + "updated_at": "2016-06-17T19:59:55.888Z", + "awardable_id": 1, + "awardable_type": "Note" +} +``` + +### Delete an award emoji -Parameters stay the same, only the note id has to be added in the URI. +Sometimes its just not meant to be, and you'll have to remove your award. Only available to +admins or the author of the award. Status code 200 on success, 401 if unauthorized. + +``` +DELETE /projects/:id/issues/:issue_id/notes/:note_id/award_emoji/:award_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `issue_id` | integer | yes | The ID of an issue | +| `note_id` | integer | yes | The ID of a note | +| `award_id` | integer | yes | The ID of a award_emoji | + +```bash +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/345 +``` + +Example Response: + +```json +{ + "id": 345, + "name": "rocket", + "user": { + "name": "Administrator", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.example.com/u/root" + }, + "created_at": "2016-06-17T19:59:55.888Z", + "updated_at": "2016-06-17T19:59:55.888Z", + "awardable_id": 1, + "awardable_type": "Note" +} +``` |