diff options
author | Robert Speicher <robert@gitlab.com> | 2016-06-17 23:49:36 +0300 |
---|---|---|
committer | Robert Speicher <rspeicher@gmail.com> | 2016-06-18 05:09:54 +0300 |
commit | d8a668b7e04516a73cb787b911dd5c412f930336 (patch) | |
tree | 9ce879311c4986405618616275545b5d83f164ab /doc | |
parent | a3d5343ee24096dac460789f0749b1ef63e51a97 (diff) |
Merge branch 'api-endpoints-award-emoji' into 'master'
API endpoints for award emoji
Closes #10884
See merge request !4575
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/README.md | 11 | ||||
-rw-r--r-- | doc/api/award_emoji.md | 367 |
2 files changed, 373 insertions, 5 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 71bb01e0d51..73f44603688 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -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. diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md new file mode 100644 index 00000000000..b44f8cfd628 --- /dev/null +++ b/doc/api/award_emoji.md @@ -0,0 +1,367 @@ +# 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 merge requests + +### 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 +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `awardable_id` | integer | yes | The ID of an awardable | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji +``` + +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", + "web_url": "http://gitlab.example.com/u/root" + }, + "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", + "web_url": "http://gitlab.example.com/u/user4" + }, + "created_at": "2016-06-15T10:09:34.177Z", + "updated_at": "2016-06-15T10:09:34.177Z", + "awardable_id": 80, + "awardable_type": "Issue" + } +] +``` + +### Get single issue note + +Gets a single award emoji + +``` +GET /projects/:id/issues/:issue_id/award_emoji/:award_id +GET /projects/:id/merge_requests/:merge_request_id/award_emoji/:award_id +``` + +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 +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/1 +``` + +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", + "web_url": "http://gitlab.example.com/u/user4" + }, + "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 +``` + +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 +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji?name=blowfish +``` + +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", + "web_url": "http://gitlab.example.com/u/root" + }, + "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 +``` + +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 +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" http://gitlab.example.com/api/v3/projects/1/issues/80/award_emoji/344 +``` + +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", + "web_url": "http://gitlab.example.com/u/root" + }, + "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 +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. + +### 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" +} +``` |