fixup! updated docs for api endpoint award emoji
This commit is contained in:
Z.J. van de Weg
parent
05a4a586b5
commit
e0bdcd2f2f
3 changed files with 188 additions and 24 deletions
|
|
@ -8,6 +8,7 @@ under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api).
|
|||
Documentation for various API resources can be found separately in the
|
||||
following locations:
|
||||
|
||||
- [Award Emoji](award_emoji.md)
|
||||
- [Branches](branches.md)
|
||||
- [Builds](builds.md)
|
||||
- [Build triggers](build_triggers.md)
|
||||
|
|
@ -44,10 +45,10 @@ The following documentation is for the [internal CI API](ci/README.md):
|
|||
|
||||
## Authentication
|
||||
|
||||
All API requests require authentication via a token. There are three types of tokens
|
||||
All API requests require authentication via a token. There are three types of tokens
|
||||
available: private tokens, OAuth 2 tokens, and personal access tokens.
|
||||
|
||||
If a token is invalid or omitted, an error message will be returned with
|
||||
If a token is invalid or omitted, an error message will be returned with
|
||||
status code `401`:
|
||||
|
||||
```json
|
||||
|
|
@ -58,8 +59,8 @@ status code `401`:
|
|||
|
||||
### Private Tokens
|
||||
|
||||
You need to pass a `private_token` parameter via query string or header. If passed as a
|
||||
header, the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of
|
||||
You need to pass a `private_token` parameter via query string or header. If passed as a
|
||||
header, the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of
|
||||
an underscore). You can find or reset your private token in your account page
|
||||
(`/profile/account`).
|
||||
|
||||
|
|
@ -80,7 +81,7 @@ Read more about [GitLab as an OAuth2 client](oauth2.md).
|
|||
|
||||
> **Note:** This feature was [introduced][ce-3749] in GitLab 8.8
|
||||
|
||||
You can create as many personal access tokens as you like from your GitLab
|
||||
You can create as many personal access tokens as you like from your GitLab
|
||||
profile (`/profile/personal_access_tokens`); perhaps one for each application
|
||||
that needs access to the GitLab API.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,14 @@
|
|||
# Award Emoji
|
||||
|
||||
>**Note:** This feature was introduced in GitLab 8.9
|
||||
|
||||
An awarded emoji tells a thousand words, and can be awarded on issues, merge
|
||||
requests and notes/comments. Issues, merge requests and notes are further called
|
||||
`awardables`.
|
||||
|
||||
## Issues and MergeRequests
|
||||
## Issues and merge requests
|
||||
|
||||
### List an awardables emoji awards
|
||||
### List an awardable's award emoji
|
||||
|
||||
Gets a list of all award emoji
|
||||
|
||||
|
|
@ -23,7 +25,7 @@ Parameters:
|
|||
| `awardable_id` | integer | yes | The ID of an awardable |
|
||||
|
||||
```bash
|
||||
curl -X GET -H "PRIVATE-TOKEN: ir6jesYP_Am5DPy7d1y7" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji
|
||||
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji
|
||||
```
|
||||
|
||||
Example Response:
|
||||
|
|
@ -39,7 +41,7 @@ Example Response:
|
|||
"id": 1,
|
||||
"state": "active",
|
||||
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
|
||||
"web_url": "http://localhost:3000/u/root"
|
||||
"web_url": "http://gitlab.example.com/u/root"
|
||||
},
|
||||
"created_at": "2016-06-15T10:09:34.206Z",
|
||||
"updated_at": "2016-06-15T10:09:34.206Z",
|
||||
|
|
@ -55,7 +57,7 @@ Example Response:
|
|||
"id": 26,
|
||||
"state": "active",
|
||||
"avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80&d=identicon",
|
||||
"web_url": "http://localhost:3000/u/user4"
|
||||
"web_url": "http://gitlab.example.com/u/user4"
|
||||
},
|
||||
"created_at": "2016-06-15T10:09:34.177Z",
|
||||
"updated_at": "2016-06-15T10:09:34.177Z",
|
||||
|
|
@ -83,7 +85,7 @@ Parameters:
|
|||
| `award_id` | integer | yes | The ID of the award emoji |
|
||||
|
||||
```bash
|
||||
curl -X GET -H "PRIVATE-TOKEN: ir6jesYP_Am5DPy7d1y7" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/1
|
||||
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/1
|
||||
```
|
||||
|
||||
Example Response:
|
||||
|
|
@ -98,7 +100,7 @@ Example Response:
|
|||
"id": 26,
|
||||
"state": "active",
|
||||
"avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80&d=identicon",
|
||||
"web_url": "http://localhost:3000/u/user4"
|
||||
"web_url": "http://gitlab.example.com/u/user4"
|
||||
},
|
||||
"created_at": "2016-06-15T10:09:34.177Z",
|
||||
"updated_at": "2016-06-15T10:09:34.177Z",
|
||||
|
|
@ -125,7 +127,7 @@ Parameters:
|
|||
| `name` | string | yes | The name of the emoji, without colons |
|
||||
|
||||
```bash
|
||||
curl -X POST -H "PRIVATE-TOKEN: ir6jesYP_Am5DPy7d1y7" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji?name=blowfish
|
||||
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji?name=blowfish
|
||||
```
|
||||
|
||||
Example Response:
|
||||
|
|
@ -140,7 +142,7 @@ Example Response:
|
|||
"id": 1,
|
||||
"state": "active",
|
||||
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
|
||||
"web_url": "http://localhost:3000/u/root"
|
||||
"web_url": "http://gitlab.example.com/u/root"
|
||||
},
|
||||
"created_at": "2016-06-17T17:47:29.266Z",
|
||||
"updated_at": "2016-06-17T17:47:29.266Z",
|
||||
|
|
@ -168,7 +170,7 @@ Parameters:
|
|||
| `award_id` | integer | yes | The ID of a award_emoji |
|
||||
|
||||
```bash
|
||||
curl -X DELETE -H "PRIVATE-TOKEN: ir6jesYP_Am5DPy7d1y7" http://localhost:3000/api/v3/projects/1/issues/80/award_emoji/344
|
||||
curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/344
|
||||
```
|
||||
|
||||
Example Response:
|
||||
|
|
@ -183,7 +185,7 @@ Example Response:
|
|||
"id": 1,
|
||||
"state": "active",
|
||||
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
|
||||
"web_url": "http://localhost:3000/u/root"
|
||||
"web_url": "http://gitlab.example.com/u/root"
|
||||
},
|
||||
"created_at": "2016-06-17T17:47:29.266Z",
|
||||
"updated_at": "2016-06-17T17:47:29.266Z",
|
||||
|
|
@ -194,11 +196,172 @@ Example Response:
|
|||
|
||||
## Award Emoji on Notes
|
||||
|
||||
The end points mentioned above are available for notes too. Notes are a sub
|
||||
resource of both Issues and MergeRequests. The endpoints changes, for example,
|
||||
to receive all awards on an issue the endpoint would be:
|
||||
`/projects/:id/issues/:issue_id/award_emoji`, for the note it would be:
|
||||
`/projects/:id/issues/:issue_id/notes/:note_id/award_emoji`. Thus after the
|
||||
resource you'd add `notes/:note_id`.
|
||||
The endpoints documented above are available for Notes as well. Notes
|
||||
are a sub-resource of Issues and Merge Requests. The examples below
|
||||
describe working with Award Emoji on notes for an Issue, but can be
|
||||
easily adapted for notes on a Merge Request.
|
||||
|
||||
Parameters stay the same, only the note id has to be added in the URI.
|
||||
### 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
|
||||
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/notes/1/award_emoji
|
||||
```
|
||||
|
||||
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",
|
||||
"web_url": "http://gitlab.example.com/u/user4"
|
||||
},
|
||||
"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
|
||||
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/notes/1/award_emoji/2
|
||||
```
|
||||
|
||||
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",
|
||||
"web_url": "http://gitlab.example.com/u/user4"
|
||||
},
|
||||
"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
|
||||
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/notes/1/award_emoji?name=rocket
|
||||
```
|
||||
|
||||
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",
|
||||
"web_url": "http://gitlab.example.com/u/root"
|
||||
},
|
||||
"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
|
||||
curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/345
|
||||
```
|
||||
|
||||
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",
|
||||
"web_url": "http://gitlab.example.com/u/root"
|
||||
},
|
||||
"created_at": "2016-06-17T19:59:55.888Z",
|
||||
"updated_at": "2016-06-17T19:59:55.888Z",
|
||||
"awardable_id": 1,
|
||||
"awardable_type": "Note"
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ describe API::API, api: true do
|
|||
let!(:award_emoji) { create(:award_emoji, awardable: issue, user: user) }
|
||||
let!(:merge_request) { create(:merge_request, source_project: project, target_project: project) }
|
||||
let!(:downvote) { create(:award_emoji, :downvote, awardable: merge_request, user: user) }
|
||||
let!(:note) { create(:note, project: project, noteable: issue) }
|
||||
let!(:note) { create(:note, project: project, noteable: issue) }
|
||||
|
||||
before { project.team << [user, :master] }
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue