/doc/api/award_emoji.md

https://gitlab.com/markglenfletcher/gitlab-ce · Markdown · 360 lines · 282 code · 78 blank · 0 comment · 0 complexity · c4a80782e992bf8fee452bfb6e738409 MD5 · raw file 

    

  1. # Award Emoji API
    2. 

  2. 

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

  4. 

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

  6. 

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

  8. 

  9. - [Issues](../user/project/issues/index.md) ([API](issues.md)).
    10. 

  10. - [Merge requests](../user/project/merge_requests/index.md) ([API](merge_requests.md)).
    11. 

  11. - [Snippets](../user/snippets.md) ([API](snippets.md)).
    12. 

  12. 

  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. 

  14. 

  15. ## Issues, merge requests, and snippets
    16. 

  16. 

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

  18. 

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

    21. 

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

  22. 

  23. ```text
    24. 

  24. GET /projects/:id/issues/:issue_iid/award_emoji
    25. 

  25. GET /projects/:id/merge_requests/:merge_request_iid/award_emoji
    26. 

  26. GET /projects/:id/snippets/:snippet_id/award_emoji
    27. 

  27. ```
    28. 

  28. 

  29. Parameters:
    30. 

  30. 

  31. | Attribute      | Type           | Required | Description                                                                  |
    32. 

  32. |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
    33. 

  33. | `id`           | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
    34. 

  34. | `issue_iid`/`merge_request_iid`/`snippet_id` | integer        | yes      | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable.     |
    35. 

  35. 

  36. Example request:
    37. 

  37. 

  38. ```sh
    39. 

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

  40. ```
    41. 

  41. 

  42. Example response:
    43. 

  43. 

  44. ```json
    45. 

  45. [
    46. 

  46.   {
    47. 

  47.     "id": 4,
    48. 

  48.     "name": "1234",
    49. 

  49.     "user": {
    50. 

  50.       "name": "Administrator",
    51. 

  51.       "username": "root",
    52. 

  52.       "id": 1,
    53. 

  53.       "state": "active",
    54. 

  54.       "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
    55. 

  55.       "web_url": "http://gitlab.example.com/root"
    56. 

  56.     },
    57. 

  57.     "created_at": "2016-06-15T10:09:34.206Z",
    58. 

  58.     "updated_at": "2016-06-15T10:09:34.206Z",
    59. 

  59.     "awardable_id": 80,
    60. 

  60.     "awardable_type": "Issue"
    61. 

  61.   },
    62. 

  62.   {
    63. 

  63.     "id": 1,
    64. 

  64.     "name": "microphone",
    65. 

  65.     "user": {
    66. 

  66.       "name": "User 4",
    67. 

  67.       "username": "user4",
    68. 

  68.       "id": 26,
    69. 

  69.       "state": "active",
    70. 

  70.       "avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80&d=identicon",
    71. 

  71.       "web_url": "http://gitlab.example.com/user4"
    72. 

  72.     },
    73. 

  73.     "created_at": "2016-06-15T10:09:34.177Z",
    74. 

  74.     "updated_at": "2016-06-15T10:09:34.177Z",
    75. 

  75.     "awardable_id": 80,
    76. 

  76.     "awardable_type": "Issue"
    77. 

  77.   }
    78. 

  78. ]
    79. 

  79. ```
    80. 

  80. 

  81. ### Get single award emoji
    82. 

  82. 

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

  84. 

  85. ```text
    86. 

  86. GET /projects/:id/issues/:issue_iid/award_emoji/:award_id
    87. 

  87. GET /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
    88. 

  88. GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
    89. 

  89. ```
    90. 

  90. 

  91. Parameters:
    92. 

  92. 

  93. | Attribute      | Type           | Required | Description                                                                  |
    94. 

  94. |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
    95. 

  95. | `id`           | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
    96. 

  96. | `issue_iid`/`merge_request_iid`/`snippet_id` | integer        | yes      | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable.     |
    97. 

  97. | `award_id`     | integer        | yes      | ID of the award emoji.                                                       |
    98. 

  98. 

  99. Example request:
    100. 

  100. 

  101. ```sh
    102. 

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

  103. ```
    104. 

  104. 

  105. Example response:
    106. 

  106. 

  107. ```json
    108. 

  108. {
    109. 

  109.   "id": 1,
    110. 

  110.   "name": "microphone",
    111. 

  111.   "user": {
    112. 

  112.     "name": "User 4",
    113. 

  113.     "username": "user4",
    114. 

  114.     "id": 26,
    115. 

  115.     "state": "active",
    116. 

  116.     "avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80&d=identicon",
    117. 

  117.     "web_url": "http://gitlab.example.com/user4"
    118. 

  118.   },
    119. 

  119.   "created_at": "2016-06-15T10:09:34.177Z",
    120. 

  120.   "updated_at": "2016-06-15T10:09:34.177Z",
    121. 

  121.   "awardable_id": 80,
    122. 

  122.   "awardable_type": "Issue"
    123. 

  123. }
    124. 

  124. ```
    125. 

  125. 

  126. ### Award a new emoji
    127. 

  127. 

  128. Create an award emoji on the specified awardable.
    129. 

  129. 

  130. ```text
    131. 

  131. POST /projects/:id/issues/:issue_iid/award_emoji
    132. 

  132. POST /projects/:id/merge_requests/:merge_request_iid/award_emoji
    133. 

  133. POST /projects/:id/snippets/:snippet_id/award_emoji
    134. 

  134. ```
    135. 

  135. 

  136. Parameters:
    137. 

  137. 

  138. | Attribute      | Type           | Required | Description                                                                  |
    139. 

  139. |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
    140. 

  140. | `id`           | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
    141. 

  141. | `issue_iid`/`merge_request_iid`/`snippet_id` | integer        | yes      | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable.     |
    142. 

  142. | `name`         | string         | yes      | Name of the emoji without colons.                                            |
    143. 

  143. 

  144. ```sh
    145. 

  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. 

  146. ```
    147. 

  147. 

  148. Example Response:
    149. 

  149. 

  150. ```json
    151. 

  151. {
    152. 

  152.   "id": 344,
    153. 

  153.   "name": "blowfish",
    154. 

  154.   "user": {
    155. 

  155.     "name": "Administrator",
    156. 

  156.     "username": "root",
    157. 

  157.     "id": 1,
    158. 

  158.     "state": "active",
    159. 

  159.     "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
    160. 

  160.     "web_url": "http://gitlab.example.com/root"
    161. 

  161.   },
    162. 

  162.   "created_at": "2016-06-17T17:47:29.266Z",
    163. 

  163.   "updated_at": "2016-06-17T17:47:29.266Z",
    164. 

  164.   "awardable_id": 80,
    165. 

  165.   "awardable_type": "Issue"
    166. 

  166. }
    167. 

  167. ```
    168. 

  168. 

  169. ### Delete an award emoji
    170. 

  170. 

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

  172. 

  173. NOTE: **Note:**
    174. 

  174. Only available to administrators or the author of the award.
    175. 

  175. 

  176. ```text
    177. 

  177. DELETE /projects/:id/issues/:issue_iid/award_emoji/:award_id
    178. 

  178. DELETE /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
    179. 

  179. DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
    180. 

  180. ```
    181. 

  181. 

  182. Parameters:
    183. 

  183. 

  184. | Attribute      | Type           | Required | Description                                                                  |
    185. 

  185. |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
    186. 

  186. | `id`           | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
    187. 

  187. | `issue_iid`/`merge_request_iid`/`snippet_id` | integer        | yes      | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable.     |
    188. 

  188. | `award_id`     | integer        | yes      | ID of an award emoji.                                                        |
    189. 

  189. 

  190. ```sh
    191. 

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

  192. ```
    193. 

  193. 

  194. ## Award Emoji on Comments
    195. 

  195. 

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

  197. 

  198. NOTE: **Note:**
    199. 

  199. The examples below describe working with award emoji on comments for an issue, but can be
    200. 

  200. easily adapted for comments on a merge request or on a snippet. Therefore, you have to replace
    201. 

  201. `issue_iid` either with `merge_request_iid` or with the `snippet_id`.
    202. 

  202. 

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

    205. 

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

  206. 

  207. ```text
    208. 

  208. GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
    209. 

  209. ```
    210. 

  210. 

  211. Parameters:
    212. 

  212. 

  213. | Attribute   | Type           | Required | Description                                                                  |
    214. 

  214. |:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
    215. 

  215. | `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
    216. 

  216. | `issue_iid` | integer        | yes      | Internal ID of an issue.                                                     |
    217. 

  217. | `note_id`   | integer        | yes      | ID of a comment (note).                                                      |
    218. 

  218. 

  219. Example request:
    220. 

  220. 

  221. ```sh
    222. 

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

  223. ```
    224. 

  224. 

  225. Example response:
    226. 

  226. 

  227. ```json
    228. 

  228. [
    229. 

  229.   {
    230. 

  230.     "id": 2,
    231. 

  231.     "name": "mood_bubble_lightning",
    232. 

  232.     "user": {
    233. 

  233.       "name": "User 4",
    234. 

  234.       "username": "user4",
    235. 

  235.       "id": 26,
    236. 

  236.       "state": "active",
    237. 

  237.       "avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80&d=identicon",
    238. 

  238.       "web_url": "http://gitlab.example.com/user4"
    239. 

  239.     },
    240. 

  240.     "created_at": "2016-06-15T10:09:34.197Z",
    241. 

  241.     "updated_at": "2016-06-15T10:09:34.197Z",
    242. 

  242.     "awardable_id": 1,
    243. 

  243.     "awardable_type": "Note"
    244. 

  244.   }
    245. 

  245. ]
    246. 

  246. ```
    247. 

  247. 

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

  249. 

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

  251. 

  252. ```text
    253. 

  253. GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
    254. 

  254. ```
    255. 

  255. 

  256. Parameters:
    257. 

  257. 

  258. | Attribute   | Type           | Required | Description                                                                  |
    259. 

  259. |:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
    260. 

  260. | `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
    261. 

  261. | `issue_iid` | integer        | yes      | Internal ID of an issue.                                                     |
    262. 

  262. | `note_id`   | integer        | yes      | ID of a comment (note).                                                      |
    263. 

  263. | `award_id`  | integer        | yes      | ID of the award emoji.                                                       |
    264. 

  264. 

  265. Example request:
    266. 

  266. 

  267. ```sh
    268. 

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

  269. ```
    270. 

  270. 

  271. Example response:
    272. 

  272. 

  273. ```json
    274. 

  274. {
    275. 

  275.   "id": 2,
    276. 

  276.   "name": "mood_bubble_lightning",
    277. 

  277.   "user": {
    278. 

  278.     "name": "User 4",
    279. 

  279.     "username": "user4",
    280. 

  280.     "id": 26,
    281. 

  281.     "state": "active",
    282. 

  282.     "avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80&d=identicon",
    283. 

  283.     "web_url": "http://gitlab.example.com/user4"
    284. 

  284.   },
    285. 

  285.   "created_at": "2016-06-15T10:09:34.197Z",
    286. 

  286.   "updated_at": "2016-06-15T10:09:34.197Z",
    287. 

  287.   "awardable_id": 1,
    288. 

  288.   "awardable_type": "Note"
    289. 

  289. }
    290. 

  290. ```
    291. 

  291. 

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

  293. 

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

  295. 

  296. ```text
    297. 

  297. POST /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
    298. 

  298. ```
    299. 

  299. 

  300. Parameters:
    301. 

  301. 

  302. | Attribute   | Type           | Required | Description                                                                  |
    303. 

  303. |:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
    304. 

  304. | `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
    305. 

  305. | `issue_iid` | integer        | yes      | Internal ID of an issue.                                                     |
    306. 

  306. | `note_id`   | integer        | yes      | ID of a comment (note).                                                      |
    307. 

  307. | `name`      | string         | yes      | Name of the emoji without colons.                                            |
    308. 

  308. 

  309. Example request:
    310. 

  310. 

  311. ```sh
    312. 

  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. 

  313. ```
    314. 

  314. 

  315. Example response:
    316. 

  316. 

  317. ```json
    318. 

  318. {
    319. 

  319.   "id": 345,
    320. 

  320.   "name": "rocket",
    321. 

  321.   "user": {
    322. 

  322.     "name": "Administrator",
    323. 

  323.     "username": "root",
    324. 

  324.     "id": 1,
    325. 

  325.     "state": "active",
    326. 

  326.     "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
    327. 

  327.     "web_url": "http://gitlab.example.com/root"
    328. 

  328.   },
    329. 

  329.   "created_at": "2016-06-17T19:59:55.888Z",
    330. 

  330.   "updated_at": "2016-06-17T19:59:55.888Z",
    331. 

  331.   "awardable_id": 1,
    332. 

  332.   "awardable_type": "Note"
    333. 

  333. }
    334. 

  334. ```
    335. 

  335. 

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

  337. 

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

  339. 

  340. NOTE: **Note:**
    341. 

  341. Only available to administrators or the author of the award.
    342. 

  342. 

  343. ```text
    344. 

  344. DELETE /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
    345. 

  345. ```
    346. 

  346. 

  347. Parameters:
    348. 

  348. 

  349. | Attribute   | Type           | Required | Description                                                                  |
    350. 

  350. |:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
    351. 

  351. | `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
    352. 

  352. | `issue_iid` | integer        | yes      | Internal ID of an issue.                                                     |
    353. 

  353. | `note_id`   | integer        | yes      | ID of a comment (note).                                                      |
    354. 

  354. | `award_id`  | integer        | yes      | ID of an award_emoji.                                                        |
    355. 

  355. 

  356. Example request:
    357. 

  357. 

  358. ```sh
    359. 

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

  360. ```
    361.