diff options
Diffstat (limited to 'doc/api/award_emoji.md')
| -rw-r--r-- | doc/api/award_emoji.md | 204 |
1 files changed, 204 insertions, 0 deletions
diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md new file mode 100644 index 00000000000..ecabc5dc7b8 --- /dev/null +++ b/doc/api/award_emoji.md @@ -0,0 +1,204 @@ +# Award Emoji + +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 + +### List an awardables emoji awards + +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 -X GET -H "PRIVATE-TOKEN: ir6jesYP_Am5DPy7d1y7" 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://localhost:3000/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://localhost:3000/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 -X GET -H "PRIVATE-TOKEN: ir6jesYP_Am5DPy7d1y7" 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://localhost:3000/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: ir6jesYP_Am5DPy7d1y7" 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://localhost:3000/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: ir6jesYP_Am5DPy7d1y7" http://localhost:3000/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://localhost:3000/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 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`. + +Parameters stay the same, only the note id has to be added in the URI. |