kotovalexarian-likes-gitlab
/
gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity

Merge branch 'docs/uplift-award-emoji-api-doc' into 'master' 

Add more information and refactor format of award emoji-related topics

See merge request gitlab-org/gitlab-ce!24288
This commit is contained in:
Achilleas Pipinellis 2019-01-16 10:30:56 +00:00
parent 28ca155be9 8c326da256
commit 7017cba31b
2 changed files with 126 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
doc/api/award_emoji.md
View File

@ -1,19 +1,26 @@
# Award Emoji API
> [Introduced][ce-4575] in GitLab 8.9, Snippet support in 8.12
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575) in GitLab 8.9. Snippet support added in 8.12.
An [awarded emoji](../user/award_emojis.md) tells a thousand words.
An awarded emoji tells a thousand words, and can be awarded on issues, merge
requests, snippets, and notes/comments. Issues, merge requests, snippets, and notes are further called
`awardables`.
Emoji can be awarded on the following (known as "awardables"):
- [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)).
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).
## Issues, merge requests, and snippets
See [Award Emoji on Comments](#award-emoji-on-comments) for information on using these endpoints with comments.
### List an awardable's award emoji
Gets a list of all award emoji
Get a list of all award emoji for a specified awardable.
```
```text
GET /projects/:id/issues/:issue_iid/award_emoji
GET /projects/:id/merge_requests/:merge_request_iid/award_emoji
GET /projects/:id/snippets/:snippet_id/award_emoji
@ -21,16 +28,18 @@ GET /projects/:id/snippets/:snippet_id/award_emoji
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
```bash
Example request:
```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji
```
Example Response:
Example response:
```json
[
@ -71,9 +80,9 @@ Example Response:
### Get single award emoji
Gets a single award emoji from an issue, snippet, or merge request.
Get a single award emoji from an issue, snippet, or merge request.
```
```text
GET /projects/:id/issues/:issue_iid/award_emoji/:award_id
GET /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
@ -81,17 +90,19 @@ GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `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 |
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
| `award_id` | integer | yes | ID of the award emoji. |
```bash
Example request:
```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/1
```
Example Response:
Example response:
```json
{
@ -114,9 +125,9 @@ Example Response:
### Award a new emoji
This end point creates an award emoji on the specified resource
Create an award emoji on the specified awardable.
```
```text
POST /projects/:id/issues/:issue_iid/award_emoji
POST /projects/:id/merge_requests/:merge_request_iid/award_emoji
POST /projects/:id/snippets/:snippet_id/award_emoji
@ -124,13 +135,13 @@ POST /projects/:id/snippets/:snippet_id/award_emoji
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `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 |
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
| `name` | string | yes | Name of the emoji without colons. |
```bash
```sh
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji?name=blowfish
```
@ -157,10 +168,12 @@ Example Response:
### 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.
Sometimes it's just not meant to be and you'll have to remove the award.
```
NOTE: **Note:**
Only available to administrators or the author of the award.
```text
DELETE /projects/:id/issues/:issue_iid/award_emoji/:award_id
DELETE /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
@ -168,43 +181,47 @@ DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `issue_iid` | integer | yes | The internal ID of an issue |
| `award_id` | integer | yes | The ID of an award_emoji |
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
| `award_id` | integer | yes | ID of an award emoji. |
```bash
```sh
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/344
```
## Award Emoji on Notes
## Award Emoji on Comments
The endpoints documented above are available for Notes as well. Notes
are a sub-resource of Issues, Merge Requests, or Snippets. The examples below
describe working with Award Emoji on notes for an Issue, but can be
easily adapted for notes on a Merge Request.
Comments (also known as notes) are a sub-resource of issues, merge requests, and snippets.
### List a note's award emoji
NOTE: **Note:**
The examples below describe working with award emoji on comments for an issue, but can be
easily adapted for comments on a merge request.
```
### List a comment's award emoji
Get all award emoji for a comment (note).
```text
GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `issue_iid` | integer | yes | The internal ID of an issue |
| `note_id` | integer | yes | The ID of a note |
| 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). |
Example request:
```bash
```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji
```
Example Response:
Example response:
```json
[
@ -227,26 +244,30 @@ Example Response:
]
```
### Get single note's award emoji
### Get an award emoji for a comment
```
Get a single award emoji for a comment (note).
```text
GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `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 |
| 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. |
```bash
Example request:
```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji/2
```
Example Response:
Example response:
```json
{
@ -267,26 +288,30 @@ Example Response:
}
```
### Award a new emoji on a note
### Award a new emoji on a comment
```
Create an award emoji on the specified comment (note).
```text
POST /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `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 |
| 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. |
```bash
Example request:
```sh
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
```
Example Response:
Example response:
```json
{
@ -307,26 +332,28 @@ Example Response:
}
```
### Delete an award emoji
### Delete an award emoji from a comment
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.
Sometimes it's just not meant to be and you'll have to remove the award.
```
NOTE: **Note:**
Only available to administrators or the author of the award.
```text
DELETE /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `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 an award_emoji |
| 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. |
```bash
Example request:
```sh
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/345
```
[ce-4575]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575

32
doc/user/award_emojis.md
View File

@ -1,24 +1,24 @@
# Award emoji
> **Notes:**
> - First [introduced][1825] in GitLab 8.2.
> - GitLab 9.0 [introduced][ce-9570] the usage of native emojis if the platform
> - First [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825) in GitLab 8.2.
> - GitLab 9.0 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9570) the usage of native emoji if the platform
> supports them and falls back to images or CSS sprites. This change greatly
> improved the award emoji performance overall.
> improved award emoji performance overall.
When you're collaborating online, you get fewer opportunities for high-fives
and thumbs-ups. Emoji can be awarded to issues, merge requests, snippets, and
virtually everywhere where you can have a discussion.
and thumbs-ups. Emoji can be awarded to [issues](project/issues/index.md), [merge requests](project/merge_requests/index.md),
[snippets](snippets.md), and anywhere you can have a discussion.
![Award emoji](img/award_emoji_select.png)
Award emoji make it much easier to give and receive feedback without a long
comment thread. Comments that are only emoji will automatically become
award emoji.
comment thread.
For information on the relevant API, see [Award Emoji API](../api/award_emoji.md).
## Sort issues and merge requests on vote count
> [Introduced][2871] in GitLab 8.5.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2781) in GitLab 8.5.
You can quickly sort issues and merge requests by the number of votes they
have received. The sort options can be found in the dropdown menu as "Most
@ -32,20 +32,16 @@ downvotes.
## Award emoji for comments
> [Introduced][4291] in GitLab 8.9.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4291) in GitLab 8.9.
Award emoji can also be applied to individual comments when you want to
celebrate an accomplishment or agree with an opinion.
To add an award emoji, click the smile in the top right of the comment and pick
an emoji from the dropdown. If you want to remove an award emoji, just click
the emoji again and the vote will be removed.
To:
- Add an award emoji, click the smile in the top right of the comment and pick an emoji from the dropdown.
- Remove an award emoji, click the emoji again and the vote will be removed.
![Picking an emoji for a comment](img/award_emoji_comment_picker.png)
![An award emoji has been applied to a comment](img/award_emoji_comment_awarded.png)
[2871]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2781
[1825]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825
[4291]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4291
[ce-9570]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9570