Add endpoints for award emoji on notes

Docs also added.

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.