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:
commit
7017cba31b
2 changed files with 126 additions and 103 deletions
|
@ -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
|
||||
|
@ -22,15 +29,17 @@ 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 |
|
||||
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
|
||||
| `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
|
||||
|
@ -82,16 +91,18 @@ 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 |
|
||||
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
|
||||
| `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
|
||||
|
@ -125,12 +136,12 @@ 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 |
|
||||
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
|
||||
| `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
|
||||
|
@ -169,42 +182,46 @@ 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 |
|
||||
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
|
||||
| `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 |
|
||||
|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
|
||||
| `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 |
|
||||
|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
|
||||
| `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 |
|
||||
|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
|
||||
| `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 |
|
||||
|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
|
||||
| `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
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in a new issue