debian-mirror-gitlab/doc/api/award_emoji.md

375 lines
9.9 KiB
Markdown
Raw Normal View History

2016-06-22 15:30:34 +05:30
# Award Emoji
2016-09-29 09:46:39 +05:30
> [Introduced][ce-4575] in GitLab 8.9, Snippet support in 8.12
2016-06-22 15:30:34 +05:30
An awarded emoji tells a thousand words, and can be awarded on issues, merge
2016-09-29 09:46:39 +05:30
requests, snippets, and notes/comments. Issues, merge requests, snippets, and notes are further called
2016-06-22 15:30:34 +05:30
`awardables`.
2016-09-29 09:46:39 +05:30
## Issues, merge requests, and snippets
2016-06-22 15:30:34 +05:30
### List an awardable's award emoji
Gets a list of all award emoji
```
GET /projects/:id/issues/:issue_id/award_emoji
GET /projects/:id/merge_requests/:merge_request_id/award_emoji
2016-09-29 09:46:39 +05:30
GET /projects/:id/snippets/:snippet_id/award_emoji
2016-06-22 15:30:34 +05:30
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `awardable_id` | integer | yes | The ID of an awardable |
```bash
2016-09-13 17:45:13 +05:30
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji
2016-06-22 15:30:34 +05:30
```
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",
2016-11-03 12:29:30 +05:30
"web_url": "http://gitlab.example.com/root"
2016-06-22 15:30:34 +05:30
},
"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",
2016-11-03 12:29:30 +05:30
"web_url": "http://gitlab.example.com/user4"
2016-06-22 15:30:34 +05:30
},
"created_at": "2016-06-15T10:09:34.177Z",
"updated_at": "2016-06-15T10:09:34.177Z",
"awardable_id": 80,
"awardable_type": "Issue"
}
]
```
2016-09-13 17:45:13 +05:30
### Get single award emoji
2016-06-22 15:30:34 +05:30
2016-09-29 09:46:39 +05:30
Gets a single award emoji from an issue, snippet, or merge request.
2016-06-22 15:30:34 +05:30
```
GET /projects/:id/issues/:issue_id/award_emoji/:award_id
GET /projects/:id/merge_requests/:merge_request_id/award_emoji/:award_id
2016-09-29 09:46:39 +05:30
GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
2016-06-22 15:30:34 +05:30
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `awardable_id` | integer | yes | The ID of an awardable |
| `award_id` | integer | yes | The ID of the award emoji |
```bash
2016-09-13 17:45:13 +05:30
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/1
2016-06-22 15:30:34 +05:30
```
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",
2016-11-03 12:29:30 +05:30
"web_url": "http://gitlab.example.com/user4"
2016-06-22 15:30:34 +05:30
},
"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
```
POST /projects/:id/issues/:issue_id/award_emoji
POST /projects/:id/merge_requests/:merge_request_id/award_emoji
2016-09-29 09:46:39 +05:30
POST /projects/:id/snippets/:snippet_id/award_emoji
2016-06-22 15:30:34 +05:30
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `awardable_id` | integer | yes | The ID of an awardable |
| `name` | string | yes | The name of the emoji, without colons |
```bash
2016-09-13 17:45:13 +05:30
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji?name=blowfish
2016-06-22 15:30:34 +05:30
```
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",
2016-11-03 12:29:30 +05:30
"web_url": "http://gitlab.example.com/root"
2016-06-22 15:30:34 +05:30
},
"created_at": "2016-06-17T17:47:29.266Z",
"updated_at": "2016-06-17T17:47:29.266Z",
"awardable_id": 80,
"awardable_type": "Issue"
}
```
### Delete an award emoji
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/award_emoji/:award_id
DELETE /projects/:id/merge_requests/:merge_request_id/award_emoji/:award_id
2016-09-29 09:46:39 +05:30
DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
2016-06-22 15:30:34 +05:30
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `issue_id` | integer | yes | The ID of an issue |
| `award_id` | integer | yes | The ID of a award_emoji |
```bash
2016-09-13 17:45:13 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/344
2016-06-22 15:30:34 +05:30
```
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",
2016-11-03 12:29:30 +05:30
"web_url": "http://gitlab.example.com/root"
2016-06-22 15:30:34 +05:30
},
"created_at": "2016-06-17T17:47:29.266Z",
"updated_at": "2016-06-17T17:47:29.266Z",
"awardable_id": 80,
"awardable_type": "Issue"
}
```
## Award Emoji on Notes
The endpoints documented above are available for Notes as well. Notes
2016-09-29 09:46:39 +05:30
are a sub-resource of Issues, Merge Requests, or Snippets. The examples below
2016-06-22 15:30:34 +05:30
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
2016-09-13 17:45:13 +05:30
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/notes/1/award_emoji
2016-06-22 15:30:34 +05:30
```
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",
2016-11-03 12:29:30 +05:30
"web_url": "http://gitlab.example.com/user4"
2016-06-22 15:30:34 +05:30
},
"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
2016-09-13 17:45:13 +05:30
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/notes/1/award_emoji/2
2016-06-22 15:30:34 +05:30
```
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",
2016-11-03 12:29:30 +05:30
"web_url": "http://gitlab.example.com/user4"
2016-06-22 15:30:34 +05:30
},
"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
2016-09-13 17:45:13 +05:30
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/notes/1/award_emoji?name=rocket
2016-06-22 15:30:34 +05:30
```
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",
2016-11-03 12:29:30 +05:30
"web_url": "http://gitlab.example.com/root"
2016-06-22 15:30:34 +05:30
},
"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
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
2016-09-13 17:45:13 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/345
2016-06-22 15:30:34 +05:30
```
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",
2016-11-03 12:29:30 +05:30
"web_url": "http://gitlab.example.com/root"
2016-06-22 15:30:34 +05:30
},
"created_at": "2016-06-17T19:59:55.888Z",
"updated_at": "2016-06-17T19:59:55.888Z",
"awardable_id": 1,
"awardable_type": "Note"
}
```
2016-09-13 17:45:13 +05:30
[ce-4575]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575