Add latest changes from gitlab-org/gitlab@master

1 files changed, 314 insertions, 0 deletions

diff --git a/doc/api/issues.md b/doc/api/issues.md
index c9f7dd71849..93f788d62a3 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -564,6 +564,320 @@ the issue still exists.
 
 ## Single issue
 
+Only for administrators. Get a single issue.
+
+The preferred way to do this is by using [personal access tokens](../user/profile/personal_access_tokens.md).
+
+```plaintext
+GET /issues/:id
+```
+
+| Attribute   | Type    | Required | Description                          |
+|-------------|---------|----------|--------------------------------------|
+| `id` | integer | yes      | The ID of the issue |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues/41"
+```
+
+Example response:
+
+```json
+{
+   "id" : 1,
+   "milestone" : {
+      "due_date" : null,
+      "project_id" : 4,
+      "state" : "closed",
+      "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
+      "iid" : 3,
+      "id" : 11,
+      "title" : "v3.0",
+      "created_at" : "2016-01-04T15:31:39.788Z",
+      "updated_at" : "2016-01-04T15:31:39.788Z",
+      "closed_at" : "2016-01-05T15:31:46.176Z"
+   },
+   "author" : {
+      "state" : "active",
+      "web_url" : "https://gitlab.example.com/root",
+      "avatar_url" : null,
+      "username" : "root",
+      "id" : 1,
+      "name" : "Administrator"
+   },
+   "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+   "state" : "closed",
+   "iid" : 1,
+   "assignees" : [{
+      "avatar_url" : null,
+      "web_url" : "https://gitlab.example.com/lennie",
+      "state" : "active",
+      "username" : "lennie",
+      "id" : 9,
+      "name" : "Dr. Luella Kovacek"
+   }],
+   "assignee" : {
+      "avatar_url" : null,
+      "web_url" : "https://gitlab.example.com/lennie",
+      "state" : "active",
+      "username" : "lennie",
+      "id" : 9,
+      "name" : "Dr. Luella Kovacek"
+   },
+   "labels" : [],
+   "upvotes": 4,
+   "downvotes": 0,
+   "merge_requests_count": 0,
+   "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
+   "updated_at" : "2016-01-04T15:31:46.176Z",
+   "created_at" : "2016-01-04T15:31:46.176Z",
+   "closed_at" : null,
+   "closed_by" : null,
+   "subscribed": false,
+   "user_notes_count": 1,
+   "due_date": null,
+   "web_url": "http://example.com/my-group/my-project/issues/1",
+   "references": {
+     "short": "#1",
+     "relative": "#1",
+     "full": "my-group/my-project#1"
+   },
+   "time_stats": {
+      "time_estimate": 0,
+      "total_time_spent": 0,
+      "human_time_estimate": null,
+      "human_total_time_spent": null
+   },
+   "confidential": false,
+   "discussion_locked": false,
+   "_links": {
+      "self": "http://example.com/api/v4/projects/1/issues/2",
+      "notes": "http://example.com/api/v4/projects/1/issues/2/notes",
+      "award_emoji": "http://example.com/api/v4/projects/1/issues/2/award_emoji",
+      "project": "http://example.com/api/v4/projects/1"
+   },
+   "task_completion_status":{
+      "count":0,
+      "completed_count":0
+   },
+   "weight": null,
+  "has_tasks": false,
+  "_links": {
+    "self": "http://gitlab.dummy:3000/api/v4/projects/1/issues/1",
+    "notes": "http://gitlab.dummy:3000/api/v4/projects/1/issues/1/notes",
+    "award_emoji": "http://gitlab.dummy:3000/api/v4/projects/1/issues/1/award_emoji",
+    "project": "http://gitlab.dummy:3000/api/v4/projects/1"
+  },
+  "references": {
+    "short": "#1",
+    "relative": "#1",
+    "full": "gitlab-org/gitlab-test#1"
+  },
+  "subscribed": true,
+  "moved_to_id": null,
+  "epic_iid": null,
+  "epic": null
+}
+```
+
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `weight` parameter:
+
+```json
+{
+   "project_id" : 4,
+   "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+   "weight": null,
+   ...
+}
+```
+
+Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) will additionally see
+the `epic` property:
+
+```javascript
+{
+   "project_id" : 4,
+   "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+   "epic": {
+   "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
+   "epic": {
+     "id" : 42,
+     "iid" : 5,
+     "title": "My epic epic",
+     "url" : "/groups/h5bp/-/epics/5",
+     "group_id": 8
+   },
+   // ...
+}
+```
+
+**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
+
+**Note**: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists.
+
+**Note**: The `epic_iid` attribute is deprecated and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157).
+Please use `iid` of the `epic` attribute instead.
+
+## Single Issue
+
+Only for administrators. Get a single issue.
+
+The preferred way to do this is by using [personal access tokens](../user/profile/personal_access_tokens.md).
+
+```plaintext
+GET /issues/:id
+```
+
+| Attribute   | Type    | Required | Description                          |
+|-------------|---------|----------|--------------------------------------|
+| `id` | integer | yes      | The ID of the issue |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues/41"
+```
+
+Example response:
+
+```json
+{
+   "id" : 1,
+   "milestone" : {
+      "due_date" : null,
+      "project_id" : 4,
+      "state" : "closed",
+      "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
+      "iid" : 3,
+      "id" : 11,
+      "title" : "v3.0",
+      "created_at" : "2016-01-04T15:31:39.788Z",
+      "updated_at" : "2016-01-04T15:31:39.788Z",
+      "closed_at" : "2016-01-05T15:31:46.176Z"
+   },
+   "author" : {
+      "state" : "active",
+      "web_url" : "https://gitlab.example.com/root",
+      "avatar_url" : null,
+      "username" : "root",
+      "id" : 1,
+      "name" : "Administrator"
+   },
+   "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+   "state" : "closed",
+   "iid" : 1,
+   "assignees" : [{
+      "avatar_url" : null,
+      "web_url" : "https://gitlab.example.com/lennie",
+      "state" : "active",
+      "username" : "lennie",
+      "id" : 9,
+      "name" : "Dr. Luella Kovacek"
+   }],
+   "assignee" : {
+      "avatar_url" : null,
+      "web_url" : "https://gitlab.example.com/lennie",
+      "state" : "active",
+      "username" : "lennie",
+      "id" : 9,
+      "name" : "Dr. Luella Kovacek"
+   },
+   "labels" : [],
+   "upvotes": 4,
+   "downvotes": 0,
+   "merge_requests_count": 0,
+   "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
+   "updated_at" : "2016-01-04T15:31:46.176Z",
+   "created_at" : "2016-01-04T15:31:46.176Z",
+   "closed_at" : null,
+   "closed_by" : null,
+   "subscribed": false,
+   "user_notes_count": 1,
+   "due_date": null,
+   "web_url": "http://example.com/my-group/my-project/issues/1",
+   "references": {
+     "short": "#1",
+     "relative": "#1",
+     "full": "my-group/my-project#1"
+   },
+   "time_stats": {
+      "time_estimate": 0,
+      "total_time_spent": 0,
+      "human_time_estimate": null,
+      "human_total_time_spent": null
+   },
+   "confidential": false,
+   "discussion_locked": false,
+   "_links": {
+      "self": "http://example.com/api/v4/projects/1/issues/2",
+      "notes": "http://example.com/api/v4/projects/1/issues/2/notes",
+      "award_emoji": "http://example.com/api/v4/projects/1/issues/2/award_emoji",
+      "project": "http://example.com/api/v4/projects/1"
+   },
+   "task_completion_status":{
+      "count":0,
+      "completed_count":0
+   },
+   "weight": null,
+  "has_tasks": false,
+  "_links": {
+    "self": "http://gitlab.dummy:3000/api/v4/projects/1/issues/1",
+    "notes": "http://gitlab.dummy:3000/api/v4/projects/1/issues/1/notes",
+    "award_emoji": "http://gitlab.dummy:3000/api/v4/projects/1/issues/1/award_emoji",
+    "project": "http://gitlab.dummy:3000/api/v4/projects/1"
+  },
+  "references": {
+    "short": "#1",
+    "relative": "#1",
+    "full": "gitlab-org/gitlab-test#1"
+  },
+  "subscribed": true,
+  "moved_to_id": null,
+  "epic_iid": null,
+  "epic": null
+}
+```
+
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `weight` parameter:
+
+```json
+{
+   "project_id" : 4,
+   "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+   "weight": null,
+   ...
+}
+```
+
+Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) will additionally see
+the `epic` property:
+
+```javascript
+{
+   "project_id" : 4,
+   "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+   "epic": {
+   "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
+   "epic": {
+     "id" : 42,
+     "iid" : 5,
+     "title": "My epic epic",
+     "url" : "/groups/h5bp/-/epics/5",
+     "group_id": 8
+   },
+   // ...
+}
+```
+
+**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
+
+**Note**: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists.
+
+**Note**: The `epic_iid` attribute is deprecated and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157).
+Please use `iid` of the `epic` attribute instead.
+
+## Single Project Issue
+
 Get a single project issue.
 
 If the project is private or the issue is confidential, you need to provide credentials to authorize.