BigW Consortium Gitlab

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

3
> [Introduced][ce-4575] in GitLab 8.9, Snippet support in 8.12
4

5

6
An awarded emoji tells a thousand words, and can be awarded on issues, merge
7
requests, snippets, and notes/comments. Issues, merge requests, snippets, and notes are further called
8 9
`awardables`.

10
## Issues, merge requests, and snippets
11

12
### List an awardable's award emoji
13 14 15 16

Gets a list of all award emoji

```
17 18
GET /projects/:id/issues/:issue_iid/award_emoji
GET /projects/:id/merge_requests/:merge_request_iid/award_emoji
19
GET /projects/:id/snippets/:snippet_id/award_emoji
20 21 22 23
```

Parameters:

24 25
| Attribute      | Type    | Required | Description                                                                 |
| ---------      | ----    | -------- | -----------                                                                 |
26
| `id`           | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user                                                         |
27
| `awardable_id` | integer | yes      | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
28 29

```bash
30
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
```

Example Response:

```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",
46
      "web_url": "http://gitlab.example.com/root"
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
    },
    "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",
62
      "web_url": "http://gitlab.example.com/user4"
63 64 65 66 67 68 69 70 71
    },
    "created_at": "2016-06-15T10:09:34.177Z",
    "updated_at": "2016-06-15T10:09:34.177Z",
    "awardable_id": 80,
    "awardable_type": "Issue"
  }
]
```

72
### Get single award emoji
73

74
Gets a single award emoji from an issue, snippet, or merge request.
75 76

```
77 78
GET /projects/:id/issues/:issue_iid/award_emoji/:award_id
GET /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
79
GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
80 81 82 83
```

Parameters:

84 85
| Attribute      | Type    | Required | Description                                                                 |
| ---------      | ----    | -------- | -----------                                                                 |
86
| `id`           | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
87 88
| `awardable_id` | integer | yes      | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
| `award_id`     | integer | yes      | The ID of the award emoji                                                   |
89 90

```bash
91
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/1
92 93 94 95 96 97 98 99 100 101 102 103 104 105
```

Example Response:

```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",
106
    "web_url": "http://gitlab.example.com/user4"
107 108 109 110 111 112 113 114 115 116 117 118 119
  },
  "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

This end point creates an award emoji on the specified resource

```
120 121
POST /projects/:id/issues/:issue_iid/award_emoji
POST /projects/:id/merge_requests/:merge_request_iid/award_emoji
122
POST /projects/:id/snippets/:snippet_id/award_emoji
123 124 125 126
```

Parameters:

127 128
| Attribute      | Type    | Required | Description                                                                 |
| ---------      | ----    | -------- | -----------                                                                 |
129
| `id`           | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
130 131
| `awardable_id` | integer | yes      | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
| `name`         | string  | yes      | The name of the emoji, without colons                                       |
132 133

```bash
134
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji?name=blowfish
135 136 137 138 139 140 141 142 143 144 145 146 147 148
```

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",
149
    "web_url": "http://gitlab.example.com/root"
150 151 152 153 154
  },
  "created_at": "2016-06-17T17:47:29.266Z",
  "updated_at": "2016-06-17T17:47:29.266Z",
  "awardable_id": 80,
  "awardable_type": "Issue"
155
}
156 157 158 159 160
```

### Delete an award emoji

Sometimes its just not meant to be, and you'll have to remove your award. Only available to
161
admins or the author of the award.
162 163

```
164 165
DELETE /projects/:id/issues/:issue_iid/award_emoji/:award_id
DELETE /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
166
DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
167 168 169 170
```

Parameters:

171 172
| Attribute   | Type    | Required | Description                 |
| ---------   | ----    | -------- | -----------                 |
173
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
174 175
| `issue_iid` | integer | yes      | The internal ID of an issue |
| `award_id`  | integer | yes      | The ID of a award_emoji     |
176 177

```bash
178
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/344
179 180 181 182
```

## Award Emoji on Notes

183
The endpoints documented above are available for Notes as well. Notes
184
are a sub-resource of Issues, Merge Requests, or Snippets. The examples below
185 186 187 188 189 190
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

```
191
GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
192 193 194 195
```

Parameters:

196 197
| Attribute   | Type    | Required | Description                 |
| ---------   | ----    | -------- | -----------                 |
198
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
199 200
| `issue_iid` | integer | yes      | The internal ID of an issue |
| `note_id`   | integer | yes      | The ID of an note           |
201 202 203


```bash
204
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji
205 206 207 208 209 210 211 212 213 214 215 216 217 218 219
```

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",
220
      "web_url": "http://gitlab.example.com/user4"
221 222 223 224 225 226 227 228 229 230 231 232
    },
    "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

```
233
GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
234 235 236 237
```

Parameters:

238 239
| Attribute   | Type    | Required | Description                 |
| ---------   | ----    | -------- | -----------                 |
240
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
241 242 243
| `issue_iid` | integer | yes      | The internal ID of an issue |
| `note_id`   | integer | yes      | The ID of a note            |
| `award_id`  | integer | yes      | The ID of the award emoji   |
244 245

```bash
246
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji/2
247 248 249 250 251 252 253 254 255 256 257 258 259 260
```

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",
261
    "web_url": "http://gitlab.example.com/user4"
262 263 264 265 266 267 268 269 270 271 272
  },
  "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

```
273
POST /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
274 275 276 277
```

Parameters:

278 279
| Attribute   | Type    | Required | Description                           |
| ---------   | ----    | -------- | -----------                           |
280
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
281 282 283
| `issue_iid` | integer | yes      | The internal ID of an issue           |
| `note_id`   | integer | yes      | The ID of a note                      |
| `name`      | string  | yes      | The name of the emoji, without colons |
284 285

```bash
286
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji?name=rocket
287 288 289 290 291 292 293 294 295 296 297 298 299 300
```

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",
301
    "web_url": "http://gitlab.example.com/root"
302 303 304 305 306 307 308 309 310
  },
  "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
311

312
Sometimes its just not meant to be, and you'll have to remove your award. Only available to
313
admins or the author of the award.
314 315

```
316
DELETE /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
317 318 319 320
```

Parameters:

321 322
| Attribute   | Type    | Required | Description                 |
| ---------   | ----    | -------- | -----------                 |
323
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
324 325 326
| `issue_iid` | integer | yes      | The internal ID of an issue |
| `note_id`   | integer | yes      | The ID of a note            |
| `award_id`  | integer | yes      | The ID of a award_emoji     |
327 328

```bash
329
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/345
330 331
```

332
[ce-4575]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575