fixup! updated docs for api endpoint award emoji

1 files changed, 181 insertions, 18 deletions

diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md
index ecabc5dc7b8..b44f8cfd628 100644
--- a/doc/api/award_emoji.md
+++ b/doc/api/award_emoji.md
@@ -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.
+
+### 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
 
-Parameters stay the same, only the note id has to be added in the URI.
+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"
+}
+```