fixup! updated docs for api endpoint award emoji

3 files changed, 188 insertions, 24 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
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"
+}
+```
diff --git a/spec/requests/api/award_emoji_spec.rb b/spec/requests/api/award_emoji_spec.rb
index 7cf2c21dae8..2e65e7f1920 100644
--- a/spec/requests/api/award_emoji_spec.rb
+++ b/spec/requests/api/award_emoji_spec.rb
@@ -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] }