Add documentation for !9530.

4 files changed, 227 insertions, 226 deletions

diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md
index 3470f8ce497..f57928d3c93 100644
--- a/doc/api/award_emoji.md
+++ b/doc/api/award_emoji.md
@@ -14,17 +14,17 @@ requests, snippets, and notes/comments. Issues, merge requests, snippets, and no
 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
+GET /projects/:id/issues/:issue_iid/award_emoji
+GET /projects/:id/merge_requests/:merge_request_iid/award_emoji
 GET /projects/:id/snippets/:snippet_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 |
+| Attribute      | Type    | Required | Description                                                                 |
+| ---------      | ----    | -------- | -----------                                                                 |
+| `id`           | integer | yes      | The ID of a project                                                         |
+| `awardable_id` | integer | yes      | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
 
 ```bash
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji
@@ -74,18 +74,18 @@ Example Response:
 Gets a single award emoji from an issue, snippet, or merge request.
 
 ```
-GET /projects/:id/issues/:issue_id/award_emoji/:award_id
-GET /projects/:id/merge_requests/:merge_request_id/award_emoji/:award_id
+GET /projects/:id/issues/:issue_iid/award_emoji/:award_id
+GET /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
 GET /projects/:id/snippets/:snippet_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 |
+| Attribute      | Type    | Required | Description                                                                 |
+| ---------      | ----    | -------- | -----------                                                                 |
+| `id`           | integer | yes      | The ID of a project                                                         |
+| `awardable_id` | integer | yes      | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
+| `award_id`     | integer | yes      | The ID of the award emoji                                                   |
 
 ```bash
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/1
@@ -117,18 +117,18 @@ Example Response:
 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
+POST /projects/:id/issues/:issue_iid/award_emoji
+POST /projects/:id/merge_requests/:merge_request_iid/award_emoji
 POST /projects/:id/snippets/:snippet_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 |
+| Attribute      | Type    | Required | Description                                                                 |
+| ---------      | ----    | -------- | -----------                                                                 |
+| `id`           | integer | yes      | The ID of a project                                                         |
+| `awardable_id` | integer | yes      | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
+| `name`         | string  | yes      | The name of the emoji, without colons                                       |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji?name=blowfish
@@ -161,18 +161,18 @@ Sometimes its just not meant to be, and you'll have to remove your award. Only a
 admins or the author of the award.
 
 ```
-DELETE /projects/:id/issues/:issue_id/award_emoji/:award_id
-DELETE /projects/:id/merge_requests/:merge_request_id/award_emoji/:award_id
+DELETE /projects/:id/issues/:issue_iid/award_emoji/:award_id
+DELETE /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
 DELETE /projects/:id/snippets/:snippet_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 |
+| Attribute   | Type    | Required | Description                 |
+| ---------   | ----    | -------- | -----------                 |
+| `id`        | integer | yes      | The ID of a project         |
+| `issue_iid` | integer | yes      | The internal ID of an issue |
+| `award_id`  | integer | yes      | The ID of a award_emoji     |
 
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/344
@@ -188,16 +188,16 @@ 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
+GET /projects/:id/issues/:issue_iid/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 |
+| Attribute   | Type    | Required | Description                 |
+| ---------   | ----    | -------- | -----------                 |
+| `id`        | integer | yes      | The ID of a project         |
+| `issue_iid` | integer | yes      | The internal ID of an issue |
+| `note_id`   | integer | yes      | The ID of an note           |
 
 
 ```bash
@@ -230,17 +230,17 @@ Example Response:
 ### Get single note's award emoji
 
 ```
-GET /projects/:id/issues/:issue_id/notes/:note_id/award_emoji/:award_id
+GET /projects/:id/issues/:issue_iid/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 |
+| Attribute   | Type    | Required | Description                 |
+| ---------   | ----    | -------- | -----------                 |
+| `id`        | integer | yes      | The ID of a project         |
+| `issue_iid` | integer | yes      | The internal 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 --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji/2
@@ -270,17 +270,17 @@ Example Response:
 ### Award a new emoji on a note
 
 ```
-POST /projects/:id/issues/:issue_id/notes/:note_id/award_emoji
+POST /projects/:id/issues/:issue_iid/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 |
+| Attribute   | Type    | Required | Description                           |
+| ---------   | ----    | -------- | -----------                           |
+| `id`        | integer | yes      | The ID of a project                   |
+| `issue_iid` | integer | yes      | The internal 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 --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji?name=rocket
@@ -313,17 +313,17 @@ Sometimes its just not meant to be, and you'll have to remove your award. Only a
 admins or the author of the award.
 
 ```
-DELETE /projects/:id/issues/:issue_id/notes/:note_id/award_emoji/:award_id
+DELETE /projects/:id/issues/:issue_iid/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 |
+| Attribute   | Type    | Required | Description                 |
+| ---------   | ----    | -------- | -----------                 |
+| `id`        | integer | yes      | The ID of a project         |
+| `issue_iid` | integer | yes      | The internal 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 --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/345
diff --git a/doc/api/issues.md b/doc/api/issues.md
index 4047ff14af2..e25841926f8 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -261,13 +261,13 @@ Example response:
 Get a single project issue.
 
 ```
-GET /projects/:id/issues/:issue_id
+GET /projects/:id/issues/:issue_iid
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `issue_id`| integer | yes   | The ID of a project's issue |
+| Attribute   | Type    | Required | Description                          |
+| ---------   | ----    | -------- | -----------                          |
+| `id`        | integer | yes      | The ID of a project                  |
+| `issue_iid` | integer | yes      | The internal ID of a project's issue |
 
 ```bash
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/41
@@ -385,22 +385,22 @@ Updates an existing project issue. This call is also used to mark an issue as
 closed.
 
 ```
-PUT /projects/:id/issues/:issue_id
+PUT /projects/:id/issues/:issue_iid
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`            | integer | yes | The ID of a project |
-| `issue_id`      | integer | yes | The ID of a project's issue |
-| `title`         | string  | no  | The title of an issue |
-| `description`   | string  | no  | The description of an issue  |
-| `confidential`  | boolean | no  | Updates an issue to be confidential |
-| `assignee_id`   | integer | no  | The ID of a user to assign the issue to |
-| `milestone_id`  | integer | no  | The ID of a milestone to assign the issue to |
-| `labels`        | string  | no  | Comma-separated label names for an issue  |
-| `state_event`   | string  | no  | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it |
-| `updated_at`    | string  | no  | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) |
-| `due_date`      | string  | no  | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` |
+| Attribute      | Type    | Required | Description                                                                                                |
+| ---------      | ----    | -------- | -----------                                                                                                |
+| `id`           | integer | yes      | The ID of a project                                                                                        |
+| `issue_iid`    | integer | yes      | The internal ID of a project's issue                                                                       |
+| `title`        | string  | no       | The title of an issue                                                                                      |
+| `description`  | string  | no       | The description of an issue                                                                                |
+| `confidential` | boolean | no       | Updates an issue to be confidential                                                                        |
+| `assignee_id`  | integer | no       | The ID of a user to assign the issue to                                                                    |
+| `milestone_id` | integer | no       | The ID of a milestone to assign the issue to                                                               |
+| `labels`       | string  | no       | Comma-separated label names for an issue                                                                   |
+| `state_event`  | string  | no       | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it                      |
+| `updated_at`   | string  | no       | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) |
+| `due_date`     | string  | no       | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11`                                           |
 
 ```bash
 curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close
@@ -444,13 +444,13 @@ Example response:
 Only for admins and project owners. Soft deletes the issue in question.
 
 ```
-DELETE /projects/:id/issues/:issue_id
+DELETE /projects/:id/issues/:issue_iid
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`            | integer | yes | The ID of a project |
-| `issue_id`      | integer | yes | The ID of a project's issue |
+| Attribute   | Type    | Required | Description                          |
+| ---------   | ----    | -------- | -----------                          |
+| `id`        | integer | yes      | The ID of a project                  |
+| `issue_iid` | integer | yes      | The internal ID of a project's issue |
 
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85
@@ -466,14 +466,14 @@ If a given label and/or milestone with the same name also exists in the target
 project, it will then be assigned to the issue that is being moved.
 
 ```
-POST /projects/:id/issues/:issue_id/move
+POST /projects/:id/issues/:issue_iid/move
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of a project |
-| `issue_id` | integer | yes | The ID of a project's issue |
-| `to_project_id` | integer | yes | The ID of the new project |
+| Attribute       | Type    | Required | Description                          |
+| ---------       | ----    | -------- | -----------                          |
+| `id`            | integer | yes      | The ID of a project                  |
+| `issue_iid`     | integer | yes      | The internal ID of a project's issue |
+| `to_project_id` | integer | yes      | The ID of the new project            |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85/move
@@ -522,13 +522,13 @@ If the user is already subscribed to the issue, the status code `304`
 is returned.
 
 ```
-POST /projects/:id/issues/:issue_id/subscribe
+POST /projects/:id/issues/:issue_iid/subscribe
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of a project |
-| `issue_id` | integer | yes | The ID of a project's issue |
+| Attribute   | Type    | Required | Description                          |
+| ---------   | ----    | -------- | -----------                          |
+| `id`        | integer | yes      | The ID of a project                  |
+| `issue_iid` | integer | yes      | The internal ID of a project's issue |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe
@@ -577,13 +577,13 @@ from it. If the user is not subscribed to the issue, the
 status code `304` is returned.
 
 ```
-POST /projects/:id/issues/:issue_id/unsubscribe
+POST /projects/:id/issues/:issue_iid/unsubscribe
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of a project |
-| `issue_id` | integer | yes | The ID of a project's issue |
+| Attribute   | Type    | Required | Description                          |
+| ---------   | ----    | -------- | -----------                          |
+| `id`        | integer | yes      | The ID of a project                  |
+| `issue_iid` | integer | yes      | The internal ID of a project's issue |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe
@@ -596,13 +596,13 @@ there already exists a todo for the user on that issue, status code `304` is
 returned.
 
 ```
-POST /projects/:id/issues/:issue_id/todo
+POST /projects/:id/issues/:issue_iid/todo
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of a project |
-| `issue_id` | integer | yes | The ID of a project's issue |
+| Attribute   | Type    | Required | Description                          |
+| ---------   | ----    | -------- | -----------                          |
+| `id`        | integer | yes      | The ID of a project                  |
+| `issue_iid` | integer | yes      | The internal ID of a project's issue |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/todo
@@ -687,14 +687,14 @@ Example response:
 Sets an estimated time of work for this issue.
 
 ```
-POST /projects/:id/issues/:issue_id/time_estimate
+POST /projects/:id/issues/:issue_iid/time_estimate
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `issue_id` | integer | yes | The ID of a project's issue |
-| `duration` | string | yes | The duration in human format. e.g: 3h30m |
+| Attribute   | Type    | Required | Description                              |
+| ---------   | ----    | -------- | -----------                              |
+| `id`        | integer | yes      | The ID of a project                      |
+| `issue_iid` | integer | yes      | The internal ID of a project's issue     |
+| `duration`  | string  | yes      | The duration in human format. e.g: 3h30m |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m
@@ -716,13 +716,13 @@ Example response:
 Resets the estimated time for this issue to 0 seconds.
 
 ```
-POST /projects/:id/issues/:issue_id/reset_time_estimate
+POST /projects/:id/issues/:issue_iid/reset_time_estimate
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `issue_id` | integer | yes | The ID of a project's issue |
+| Attribute   | Type    | Required | Description                          |
+| ---------   | ----    | -------- | -----------                          |
+| `id`        | integer | yes      | The ID of a project                  |
+| `issue_iid` | integer | yes      | The internal ID of a project's issue |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate
@@ -744,14 +744,14 @@ Example response:
 Adds spent time for this issue
 
 ```
-POST /projects/:id/issues/:issue_id/add_spent_time
+POST /projects/:id/issues/:issue_iid/add_spent_time
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `issue_id` | integer | yes | The ID of a project's issue |
-| `duration` | string | yes | The duration in human format. e.g: 3h30m |
+| Attribute   | Type    | Required | Description                              |
+| ---------   | ----    | -------- | -----------                              |
+| `id`        | integer | yes      | The ID of a project                      |
+| `issue_iid` | integer | yes      | The internal ID of a project's issue     |
+| `duration`  | string  | yes      | The duration in human format. e.g: 3h30m |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h
@@ -773,13 +773,13 @@ Example response:
 Resets the total spent time for this issue to 0 seconds.
 
 ```
-POST /projects/:id/issues/:issue_id/reset_spent_time
+POST /projects/:id/issues/:issue_iid/reset_spent_time
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `issue_id` | integer | yes | The ID of a project's issue |
+| Attribute   | Type    | Required | Description                          |
+| ---------   | ----    | -------- | -----------                          |
+| `id`        | integer | yes      | The ID of a project                  |
+| `issue_iid` | integer | yes      | The internal ID of a project's issue |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time
@@ -799,13 +799,13 @@ Example response:
 ## Get time tracking stats
 
 ```
-GET /projects/:id/issues/:issue_id/time_stats
+GET /projects/:id/issues/:issue_iid/time_stats
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `issue_id` | integer | yes | The ID of a project's issue |
+| Attribute   | Type    | Required | Description                          |
+| ---------   | ----    | -------- | -----------                          |
+| `id`        | integer | yes      | The ID of a project                  |
+| `issue_iid` | integer | yes      | The internal ID of a project's issue |
 
 ```bash
 curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 09d23cd2ff6..80ef5fbc51c 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -82,13 +82,13 @@ Parameters:
 Shows information about a single merge request.
 
 ```
-GET /projects/:id/merge_requests/:merge_request_id
+GET /projects/:id/merge_requests/:merge_request_iid
 ```
 
 Parameters:
 
-- `id` (required) - The ID of a project
-- `merge_request_id` (required) - The ID of MR
+- `iid` (required) - The ID of a project
+- `merge_request_iid` (required) - The internal ID of the merge request
 
 ```json
 {
@@ -150,13 +150,13 @@ Parameters:
 Get a list of merge request commits.
 
 ```
-GET /projects/:id/merge_requests/:merge_request_id/commits
+GET /projects/:id/merge_requests/:merge_request_iid/commits
 ```
 
 Parameters:
 
 - `id` (required) - The ID of a project
-- `merge_request_id` (required) - The ID of MR
+- `merge_request_iid` (required) - The internal ID of the merge request
 
 
 ```json
@@ -187,13 +187,13 @@ Parameters:
 Shows information about the merge request including its files and changes.
 
 ```
-GET /projects/:id/merge_requests/:merge_request_id/changes
+GET /projects/:id/merge_requests/:merge_request_iid/changes
 ```
 
 Parameters:
 
 - `id` (required) - The ID of a project
-- `merge_request_id` (required) - The ID of MR
+- `merge_request_iid` (required) - The internal ID of the merge request
 
 ```json
 {
@@ -269,18 +269,18 @@ Creates a new merge request.
 POST /projects/:id/merge_requests
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`            | string  | yes | The ID of a project |
-| `source_branch` | string  | yes | The source branch |
-| `target_branch` | string  | yes | The target branch |
-| `title`         | string  | yes | Title of MR |
-| `assignee_id`   | integer | no  | Assignee user ID |
-| `description`   | string  | no  | Description of MR |
-| `target_project_id` | integer  | no | The target project (numeric id) |
-| `labels` | string  | no | Labels for MR as a comma-separated list |
-| `milestone_id` | integer  | no | The ID of a milestone |
-| `remove_source_branch` | boolean  | no | Flag indicating if a merge request should remove the source branch when merging |
+| Attribute              | Type    | Required | Description                                                                     |
+| ---------              | ----    | -------- | -----------                                                                     |
+| `id`                   | string  | yes      | The ID of a project                                                             |
+| `source_branch`        | string  | yes      | The source branch                                                               |
+| `target_branch`        | string  | yes      | The target branch                                                               |
+| `title`                | string  | yes      | Title of MR                                                                     |
+| `assignee_id`          | integer | no       | Assignee user ID                                                                |
+| `description`          | string  | no       | Description of MR                                                               |
+| `target_project_id`    | integer | no       | The target project (numeric id)                                                 |
+| `labels`               | string  | no       | Labels for MR as a comma-separated list                                         |
+| `milestone_id`         | integer | no       | The ID of a milestone                                                           |
+| `remove_source_branch` | boolean | no       | Flag indicating if a merge request should remove the source branch when merging |
 
 ```json
 {
@@ -342,21 +342,21 @@ POST /projects/:id/merge_requests
 Updates an existing merge request. You can change the target branch, title, or even close the MR.
 
 ```
-PUT /projects/:id/merge_requests/:merge_request_id
+PUT /projects/:id/merge_requests/:merge_request_iid
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`            | string  | yes | The ID of a project |
-| `merge_request_id` | integer  | yes | The ID of a merge request |
-| `target_branch` | string  | no | The target branch |
-| `title`         | string  | no | Title of MR |
-| `assignee_id`   | integer | no  | Assignee user ID |
-| `description`   | string  | no  | Description of MR |
-| `state_event` | string  | no | New state (close/reopen) |
-| `labels` | string  | no | Labels for MR as a comma-separated list |
-| `milestone_id` | integer  | no | The ID of a milestone |
-| `remove_source_branch` | boolean  | no | Flag indicating if a merge request should remove the source branch when merging |
+| Attribute              | Type    | Required | Description                                                                     |
+| ---------              | ----    | -------- | -----------                                                                     |
+| `id`                   | string  | yes      | The ID of a project                                                             |
+| `merge_request_iid`    | integer | yes      | The ID of a merge request                                                       |
+| `target_branch`        | string  | no       | The target branch                                                               |
+| `title`                | string  | no       | Title of MR                                                                     |
+| `assignee_id`          | integer | no       | Assignee user ID                                                                |
+| `description`          | string  | no       | Description of MR                                                               |
+| `state_event`          | string  | no       | New state (close/reopen)                                                        |
+| `labels`               | string  | no       | Labels for MR as a comma-separated list                                         |
+| `milestone_id`         | integer | no       | The ID of a milestone                                                           |
+| `remove_source_branch` | boolean | no       | Flag indicating if a merge request should remove the source branch when merging |
 
 Must include at least one non-required attribute from above.
 
@@ -419,13 +419,13 @@ Must include at least one non-required attribute from above.
 Only for admins and project owners. Soft deletes the merge request in question.
 
 ```
-DELETE /projects/:id/merge_requests/:merge_request_id
+DELETE /projects/:id/merge_requests/:merge_request_iid
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`            | integer | yes | The ID of a project |
-| `merge_request_id` | integer | yes | The ID of a project's merge request |
+| Attribute           | Type    | Required | Description                          |
+| ---------           | ----    | -------- | -----------                          |
+| `id`                | integer | yes      | The ID of a project                  |
+| `merge_request_iid` | integer | yes      | The internal ID of the merge request |
 
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/merge_requests/85
@@ -445,13 +445,13 @@ If the `sha` parameter is passed and does not match the HEAD of the source - you
 If you don't have permissions to accept this merge request - you'll get a `401`
 
 ```
-PUT /projects/:id/merge_requests/:merge_request_id/merge
+PUT /projects/:id/merge_requests/:merge_request_iid/merge
 ```
 
 Parameters:
 
 - `id` (required)                           - The ID of a project
-- `merge_request_id` (required)             - ID of MR
+- `merge_request_iid` (required)            - Internal ID of MR
 - `merge_commit_message` (optional)         - Custom merge commit message
 - `should_remove_source_branch` (optional)  - if `true` removes the source branch
 - `merge_when_pipeline_succeeds` (optional)    - if `true` the MR is merged when the pipeline succeeds
@@ -520,12 +520,12 @@ If the merge request is already merged or closed - you get `405` and error messa
 
 In case the merge request is not set to be merged when the pipeline succeeds, you'll also get a `406` error.
 ```
-PUT /projects/:id/merge_requests/:merge_request_id/cancel_merge_when_pipeline_succeeds
+PUT /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_succeeds
 ```
 Parameters:
 
 - `id` (required)                           - The ID of a project
-- `merge_request_id` (required)             - ID of MR
+- `merge_request_iid` (required)            - Internal ID of MR
 
 ```json
 {
@@ -591,13 +591,13 @@ Comments are done via the [notes](notes.md) resource.
 Get all the issues that would be closed by merging the provided merge request.
 
 ```
-GET /projects/:id/merge_requests/:merge_request_id/closes_issues
+GET /projects/:id/merge_requests/:merge_request_iid/closes_issues
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `merge_request_id` | integer | yes   | The ID of the merge request |
+| Attribute           | Type    | Required | Description                          |
+| ---------           | ----    | -------- | -----------                          |
+| `id`                | integer | yes      | The ID of a project                  |
+| `merge_request_iid` | integer | yes      | The internal ID of the merge request |
 
 ```bash
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/76/merge_requests/1/closes_issues
@@ -666,13 +666,13 @@ Subscribes the authenticated user to a merge request to receive notification. If
 status code `304` is returned.
 
 ```
-POST /projects/:id/merge_requests/:merge_request_id/subscribe
+POST /projects/:id/merge_requests/:merge_request_iid/subscribe
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of a project |
-| `merge_request_id` | integer | yes   | The ID of the merge request |
+| Attribute           | Type    | Required | Description                 |
+| ---------           | ----    | -------- | -----------                 |
+| `id`                | integer | yes      | The ID of a project         |
+| `merge_request_iid` | integer | yes      | The internal ID of the merge request |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/17/subscribe
@@ -740,13 +740,13 @@ notifications from that merge request. If the user is
 not subscribed to the merge request, the status code `304` is returned.
 
 ```
-POST /projects/:id/merge_requests/:merge_request_id/unsubscribe
+POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of a project |
-| `merge_request_id` | integer | yes   | The ID of the merge request |
+| Attribute           | Type    | Required | Description                          |
+| ---------           | ----    | -------- | -----------                          |
+| `id`                | integer | yes      | The ID of a project                  |
+| `merge_request_iid` | integer | yes      | The internal ID of the merge request |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/17/unsubscribe
@@ -814,13 +814,13 @@ If there already exists a todo for the user on that merge request,
 status code `304` is returned.
 
 ```
-POST /projects/:id/merge_requests/:merge_request_id/todo
+POST /projects/:id/merge_requests/:merge_request_iid/todo
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of a project |
-| `merge_request_id` | integer | yes   | The ID of the merge request |
+| Attribute           | Type    | Required | Description                          |
+| ---------           | ----    | -------- | -----------                          |
+| `id`                | integer | yes      | The ID of a project                  |
+| `merge_request_iid` | integer | yes      | The internal ID of the merge request |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/27/todo
@@ -914,13 +914,13 @@ Example response:
 Get a list of merge request diff versions.
 
 ```
-GET /projects/:id/merge_requests/:merge_request_id/versions
+GET /projects/:id/merge_requests/:merge_request_iid/versions
 ```
 
-| Attribute | Type    | Required | Description           |
-| --------- | ------- | -------- | --------------------- |
-| `id`      | String  | yes      | The ID of the project |
-| `merge_request_id` | integer | yes | The ID of the merge request |
+| Attribute           | Type    | Required | Description                 |
+| ---------           | ------- | -------- | ---------------------       |
+| `id`                | String  | yes      | The ID of the project       |
+| `merge_request_iid` | integer | yes      | The internal ID of the merge request |
 
 ```bash
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/merge_requests/1/versions
@@ -955,14 +955,14 @@ Example response:
 Get a single merge request diff version.
 
 ```
-GET /projects/:id/merge_requests/:merge_request_id/versions/:version_id
+GET /projects/:id/merge_requests/:merge_request_iid/versions/:version_id
 ```
 
-| Attribute | Type    | Required | Description           |
-| --------- | ------- | -------- | --------------------- |
-| `id`      | String  | yes      | The ID of the project |
-| `merge_request_id` | integer | yes | The ID of the merge request |
-| `version_id` | integer | yes | The ID of the merge request diff version |
+| Attribute           | Type    | Required | Description                              |
+| ---------           | ------- | -------- | ---------------------                    |
+| `id`                | String  | yes      | The ID of the project                    |
+| `merge_request_iid` | integer | yes      | The internal ID of the merge request     |
+| `version_id`        | integer | yes      | The ID of the merge request diff version |
 
 ```bash
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/merge_requests/1/versions/1
@@ -1022,14 +1022,14 @@ Example response:
 Sets an estimated time of work for this merge request.
 
 ```
-POST /projects/:id/merge_requests/:merge_request_id/time_estimate
+POST /projects/:id/merge_requests/:merge_request_iid/time_estimate
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `merge_request_id` | integer | yes | The ID of a project's merge request |
-| `duration` | string | yes | The duration in human format. e.g: 3h30m |
+| Attribute           | Type    | Required | Description                              |
+| ---------           | ----    | -------- | -----------                              |
+| `id`                | integer | yes      | The ID of a project                      |
+| `merge_request_iid` | integer | yes      | The internal ID of the merge request     |
+| `duration`          | string  | yes      | The duration in human format. e.g: 3h30m |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/time_estimate?duration=3h30m
@@ -1051,13 +1051,13 @@ Example response:
 Resets the estimated time for this merge request to 0 seconds.
 
 ```
-POST /projects/:id/merge_requests/:merge_request_id/reset_time_estimate
+POST /projects/:id/merge_requests/:merge_request_iid/reset_time_estimate
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `merge_request_id` | integer | yes | The ID of a project's merge_request |
+| Attribute           | Type    | Required | Description                                  |
+| ---------           | ----    | -------- | -----------                                  |
+| `id`                | integer | yes      | The ID of a project                          |
+| `merge_request_iid` | integer | yes      | The internal ID of a project's merge_request |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/reset_time_estimate
@@ -1079,14 +1079,14 @@ Example response:
 Adds spent time for this merge request
 
 ```
-POST /projects/:id/merge_requests/:merge_request_id/add_spent_time
+POST /projects/:id/merge_requests/:merge_request_iid/add_spent_time
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `merge_request_id` | integer | yes | The ID of a project's merge request |
-| `duration` | string | yes | The duration in human format. e.g: 3h30m |
+| Attribute           | Type    | Required | Description                              |
+| ---------           | ----    | -------- | -----------                              |
+| `id`                | integer | yes      | The ID of a project                      |
+| `merge_request_iid` | integer | yes      | The internal ID of the merge request     |
+| `duration`          | string  | yes      | The duration in human format. e.g: 3h30m |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/add_spent_time?duration=1h
@@ -1108,13 +1108,13 @@ Example response:
 Resets the total spent time for this merge request to 0 seconds.
 
 ```
-POST /projects/:id/merge_requests/:merge_request_id/reset_spent_time
+POST /projects/:id/merge_requests/:merge_request_iid/reset_spent_time
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `merge_request_id` | integer | yes | The ID of a project's merge_request |
+| Attribute           | Type    | Required | Description                                  |
+| ---------           | ----    | -------- | -----------                                  |
+| `id`                | integer | yes      | The ID of a project                          |
+| `merge_request_iid` | integer | yes      | The internal ID of a project's merge_request |
 
 ```bash
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/reset_spent_time
@@ -1134,13 +1134,13 @@ Example response:
 ## Get time tracking stats
 
 ```
-GET /projects/:id/merge_requests/:merge_request_id/time_stats
+GET /projects/:id/merge_requests/:merge_request_iid/time_stats
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of a project |
-| `merge_request_id` | integer | yes | The ID of a project's merge request |
+| Attribute           | Type    | Required | Description                          |
+| ---------           | ----    | -------- | -----------                          |
+| `id`                | integer | yes      | The ID of a project                  |
+| `merge_request_iid` | integer | yes      | The internal ID of the merge request |
 
 ```bash
 curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/time_stats
diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md
index 5af775860ca..f42a5e9158b 100644
--- a/doc/api/v3_to_v4.md
+++ b/doc/api/v3_to_v4.md
@@ -69,4 +69,5 @@ changes are in V4:
   - `POST /projects/:id/trigger/builds` to `POST /projects/:id/trigger/pipeline`
   - Require description when creating a new trigger `POST /projects/:id/triggers`
 - Simplify project payload exposed on Environment endpoints [!9675](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9675)
-
+- API uses merge request `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the merge requests, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9530)
+- API uses issue `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the issues, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9530)