root
/
gitlab-ce
mirror of https://gitlab.com/free-releases/gitlab-ce.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

fixup! updated docs for api endpoint award emoji

This commit is contained in:
Z.J. van de Weg 2016-06-17 22:03:57 +02:00
parent 05a4a586b5
commit e0bdcd2f2f
3 changed files with 188 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
doc/api/README.md
View File

@ -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.

199
doc/api/award_emoji.md
View File

@ -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"
}
```

2
spec/requests/api/award_emoji_spec.rb
View File

@ -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] }