award_emoji.md 12.9 KB
Newer Older
1
# Award Emoji API
2

3
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575) in GitLab 8.9. Snippet support added in 8.12.
4

5
An [awarded emoji](../user/award_emojis.md) tells a thousand words.
6

7
Emoji can be awarded on the following (known as "awardables"):
8

Evan Read's avatar
Evan Read committed
9 10 11
- [Issues](../user/project/issues/index.md) ([API](issues.md)).
- [Merge requests](../user/project/merge_requests/index.md) ([API](merge_requests.md)).
- [Snippets](../user/snippets.md) ([API](snippets.md)).
12

Evan Read's avatar
Evan Read committed
13
Emoji can also [be awarded](../user/award_emojis.html#award-emoji-for-comments) on comments (also known as notes). See also [Notes API](notes.md).
14

15
## Issues, merge requests, and snippets
16

17
See [Award Emoji on Comments](#award-emoji-on-comments) for information on using these endpoints with comments.
18

19
### List an awardable's award emoji
20

21
Get a list of all award emoji for a specified awardable.
22

23
```text
24 25
GET /projects/:id/issues/:issue_iid/award_emoji
GET /projects/:id/merge_requests/:merge_request_iid/award_emoji
26
GET /projects/:id/snippets/:snippet_id/award_emoji
27 28 29 30
```

Parameters:

31 32 33
| Attribute      | Type           | Required | Description                                                                  |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id`           | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
34
| `issue_iid`/`merge_request_iid`/`snippet_id` | integer        | yes      | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable.     |
35

36 37 38
Example request:

```sh
39
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji
40 41
```

42
Example response:
43 44 45 46 47 48 49 50 51 52 53 54

```json
[
  {
    "id": 4,
    "name": "1234",
    "user": {
      "name": "Administrator",
      "username": "root",
      "id": 1,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
55
      "web_url": "http://gitlab.example.com/root"
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
    },
    "created_at": "2016-06-15T10:09:34.206Z",
    "updated_at": "2016-06-15T10:09:34.206Z",
    "awardable_id": 80,
    "awardable_type": "Issue"
  },
  {
    "id": 1,
    "name": "microphone",
    "user": {
      "name": "User 4",
      "username": "user4",
      "id": 26,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80&d=identicon",
71
      "web_url": "http://gitlab.example.com/user4"
72 73 74 75 76 77 78 79 80
    },
    "created_at": "2016-06-15T10:09:34.177Z",
    "updated_at": "2016-06-15T10:09:34.177Z",
    "awardable_id": 80,
    "awardable_type": "Issue"
  }
]
```

81
### Get single award emoji
82

83
Get a single award emoji from an issue, snippet, or merge request.
84

85
```text
86 87
GET /projects/:id/issues/:issue_iid/award_emoji/:award_id
GET /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
88
GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
89 90 91 92
```

Parameters:

93 94 95
| Attribute      | Type           | Required | Description                                                                  |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id`           | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
96
| `issue_iid`/`merge_request_iid`/`snippet_id` | integer        | yes      | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable.     |
97
| `award_id`     | integer        | yes      | ID of the award emoji.                                                       |
98 99

Example request:
100

101
```sh
102
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/1
103 104
```

105
Example response:
106 107 108 109 110 111 112 113 114 115 116

```json
{
  "id": 1,
  "name": "microphone",
  "user": {
    "name": "User 4",
    "username": "user4",
    "id": 26,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80&d=identicon",
117
    "web_url": "http://gitlab.example.com/user4"
118 119 120 121 122 123 124 125 126 127
  },
  "created_at": "2016-06-15T10:09:34.177Z",
  "updated_at": "2016-06-15T10:09:34.177Z",
  "awardable_id": 80,
  "awardable_type": "Issue"
}
```

### Award a new emoji

128
Create an award emoji on the specified awardable.
129

130
```text
131 132
POST /projects/:id/issues/:issue_iid/award_emoji
POST /projects/:id/merge_requests/:merge_request_iid/award_emoji
133
POST /projects/:id/snippets/:snippet_id/award_emoji
134 135 136 137
```

Parameters:

138 139 140
| Attribute      | Type           | Required | Description                                                                  |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id`           | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
141
| `issue_iid`/`merge_request_iid`/`snippet_id` | integer        | yes      | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable.     |
142
| `name`         | string         | yes      | Name of the emoji without colons.                                            |
143

144
```sh
145
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji?name=blowfish
146 147 148 149 150 151 152 153 154 155 156 157 158 159
```

Example Response:

```json
{
  "id": 344,
  "name": "blowfish",
  "user": {
    "name": "Administrator",
    "username": "root",
    "id": 1,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
160
    "web_url": "http://gitlab.example.com/root"
161 162 163 164 165
  },
  "created_at": "2016-06-17T17:47:29.266Z",
  "updated_at": "2016-06-17T17:47:29.266Z",
  "awardable_id": 80,
  "awardable_type": "Issue"
166
}
167 168 169 170
```

### Delete an award emoji

171
Sometimes it's just not meant to be and you'll have to remove the award.
172

173 174 175 176
NOTE: **Note:**
Only available to administrators or the author of the award.

```text
177 178
DELETE /projects/:id/issues/:issue_iid/award_emoji/:award_id
DELETE /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
179
DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
180 181 182 183
```

Parameters:

184 185 186
| Attribute      | Type           | Required | Description                                                                  |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id`           | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
187
| `issue_iid`/`merge_request_iid`/`snippet_id` | integer        | yes      | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable.     |
188
| `award_id`     | integer        | yes      | ID of an award emoji.                                                        |
189

190
```sh
191
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/344
192 193
```

194
## Award Emoji on Comments
195

196
Comments (also known as notes) are a sub-resource of issues, merge requests, and snippets.
197

198
NOTE: **Note:**
199
The examples below describe working with award emoji on comments for an issue, but can be
200 201
easily adapted for comments on a merge request or on a snippet. Therefore, you have to replace
`issue_iid` either with `merge_request_iid` or with the `snippet_id`.
202

203
### List a comment's award emoji
204

205
Get all award emoji for a comment (note).
206 207

```text
208
GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
209 210 211 212
```

Parameters:

213 214 215 216 217
| Attribute   | Type           | Required | Description                                                                  |
|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `issue_iid` | integer        | yes      | Internal ID of an issue.                                                     |
| `note_id`   | integer        | yes      | ID of a comment (note).                                                      |
218

219
Example request:
220

221
```sh
222
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji
223 224
```

225
Example response:
226 227 228 229 230 231 232 233 234 235 236 237

```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",
238
      "web_url": "http://gitlab.example.com/user4"
239 240 241 242 243 244 245 246 247
    },
    "created_at": "2016-06-15T10:09:34.197Z",
    "updated_at": "2016-06-15T10:09:34.197Z",
    "awardable_id": 1,
    "awardable_type": "Note"
  }
]
```

248
### Get an award emoji for a comment
249

250
Get a single award emoji for a comment (note).
251 252

```text
253
GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
254 255 256 257
```

Parameters:

258 259 260 261 262 263
| Attribute   | Type           | Required | Description                                                                  |
|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `issue_iid` | integer        | yes      | Internal ID of an issue.                                                     |
| `note_id`   | integer        | yes      | ID of a comment (note).                                                      |
| `award_id`  | integer        | yes      | ID of the award emoji.                                                       |
264 265

Example request:
266

267
```sh
268
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji/2
269 270
```

271
Example response:
272 273 274 275 276 277 278 279 280 281 282

```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",
283
    "web_url": "http://gitlab.example.com/user4"
284 285 286 287 288 289 290 291
  },
  "created_at": "2016-06-15T10:09:34.197Z",
  "updated_at": "2016-06-15T10:09:34.197Z",
  "awardable_id": 1,
  "awardable_type": "Note"
}
```

292
### Award a new emoji on a comment
293

294
Create an award emoji on the specified comment (note).
295 296

```text
297
POST /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
298 299 300 301
```

Parameters:

302 303 304 305 306 307
| Attribute   | Type           | Required | Description                                                                  |
|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `issue_iid` | integer        | yes      | Internal ID of an issue.                                                     |
| `note_id`   | integer        | yes      | ID of a comment (note).                                                      |
| `name`      | string         | yes      | Name of the emoji without colons.                                            |
308

309 310 311
Example request:

```sh
312
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji?name=rocket
313 314
```

315
Example response:
316 317 318 319 320 321 322 323 324 325 326

```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",
327
    "web_url": "http://gitlab.example.com/root"
328 329 330 331 332 333 334 335
  },
  "created_at": "2016-06-17T19:59:55.888Z",
  "updated_at": "2016-06-17T19:59:55.888Z",
  "awardable_id": 1,
  "awardable_type": "Note"
}
```

336
### Delete an award emoji from a comment
337

338
Sometimes it's just not meant to be and you'll have to remove the award.
339

340 341 342 343
NOTE: **Note:**
Only available to administrators or the author of the award.

```text
344
DELETE /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
345 346 347 348
```

Parameters:

349 350 351 352 353 354
| Attribute   | Type           | Required | Description                                                                  |
|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `issue_iid` | integer        | yes      | Internal ID of an issue.                                                     |
| `note_id`   | integer        | yes      | ID of a comment (note).                                                      |
| `award_id`  | integer        | yes      | ID of an award_emoji.                                                        |
355 356

Example request:
357

358
```sh
359
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/345
360
```