Skip to content

G
gitlab-ce
Commit 07f277b8 authored by Marcin Sedlak-Jakubowski's avatar Marcin Sedlak-Jakubowski
Browse files
Options

Merge branch 'epic-doc-fix' into 'master' 

Changed doc/api/issues.md for consistency issues

See merge request gitlab-org/gitlab!59636
parents 61d86343 0d52cda1
Hide whitespace changes
Inline Side-by-side
Showing with 218 additions and 46 deletions
doc/api/issues.md
View file @ 07f277b8
......@@ -27,6 +27,8 @@ When requested across groups or projects, it's expected to be the same as the `f
## List issues
> Moved `weight` to [GitLab Premium](https://about.gitlab.com/pricing/) due to Starter/Bronze being [discontinued](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) in 13.9.
Get all issues the authenticated user has access to. By default it
returns only issues created by the current user. To get all issues,
use parameter `scope=all`.
......@@ -75,7 +77,7 @@ GET /issues?state=opened
| `state` | string | no | Return `all` issues or just those that are `opened` or `closed` |
| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. |
| `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. |
| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413)|
```shell
......@@ -169,8 +171,7 @@ Example response:
]
```
Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see
the `weight` parameter:
Issues created by users on GitLab Premium or higher include the `weight` property:
```json
[
......@@ -183,8 +184,25 @@ the `weight` parameter:
]
```
Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see
the `health_status` parameter:
Issues created by users on GitLab Premium or higher include the `epic` property:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"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
},
...
}
```
Issues created by users on GitLab Ultimate include the `health_status` property:
```json
[
......@@ -201,6 +219,10 @@ WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform
to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157).
Please use `iid` of the `epic` attribute instead.
NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042).
This value is only present for issues closed after GitLab 10.6 and if the user account
......@@ -208,6 +230,8 @@ that closed the issue still exists.
## List group issues
> Moved `weight` to [GitLab Premium](https://about.gitlab.com/pricing/) due to Starter/Bronze being [discontinued](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) in 13.9.
Get a list of a group's issues.
If the group is private, credentials need to be provided for authorization.
......@@ -256,7 +280,7 @@ GET /groups/:id/issues?state=opened
| `state` | string | no | Return all issues or just those that are `opened` or `closed` |
| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. |
| `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. |
| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) |
```shell
......@@ -349,8 +373,7 @@ Example response:
]
```
Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see
the `weight` parameter:
Issues created by users on GitLab Premium or higher include the `weight` property:
```json
[
......@@ -363,8 +386,25 @@ the `weight` parameter:
]
```
Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see
the `health_status` parameter:
Issues created by users on GitLab Premium or higher include the `epic` property:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"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
},
...
}
```
Issues created by users on GitLab Ultimate include the `health_status` property:
```json
[
......@@ -380,6 +420,10 @@ the `health_status` parameter:
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157).
Please use `iid` of the `epic` attribute instead.
NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042).
This value is only present for issues closed after GitLab 10.6 and if the user account that closed
......@@ -387,6 +431,8 @@ the issue still exists.
## List project issues
> Moved `weight` to [GitLab Premium](https://about.gitlab.com/pricing/) due to Starter/Bronze being [discontinued](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) in 13.9.
Get a list of a project's issues.
If the project is private, you need to provide credentials to authorize.
......@@ -434,7 +480,7 @@ GET /projects/:id/issues?state=opened
| `state` | string | no | Return all issues or just those that are `opened` or `closed` |
| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. |
| `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. |
| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. `description_html` was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) |
```shell
......@@ -534,8 +580,7 @@ Example response:
]
```
Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see
the `weight` parameter:
Issues created by users on GitLab Premium or higher include the `weight` property:
```json
[
......@@ -548,8 +593,25 @@ the `weight` parameter:
]
```
Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see
the `health_status` parameter:
Issues created by users on GitLab Premium or higher include the `epic` property:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"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
},
...
}
```
Issues created by users on GitLab Ultimate include the `health_status` property:
```json
[
......@@ -565,6 +627,10 @@ the `health_status` parameter:
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157).
Please use `iid` of the `epic` attribute instead.
NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
......@@ -672,14 +738,11 @@ Example response:
"project": "http://gitlab.example:3000/api/v4/projects/1"
},
"moved_to_id": null,
"service_desk_reply_to": "service.desk@gitlab.com",
"epic_iid": null,
"epic": null
"service_desk_reply_to": "service.desk@gitlab.com"
}
```
Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see
the `weight` parameter:
Issues created by users on GitLab Premium or higher include the `weight` property:
```json
{
......@@ -690,10 +753,9 @@ the `weight` parameter:
}
```
Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see
the `epic` property:
Issues created by users on GitLab Premium or higher include the `epic` property:
```javascript
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
......@@ -706,10 +768,24 @@ the `epic` property:
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
// ...
...
}
```
Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status`
property:
```json
[
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"health_status": "on_track",
...
}
]
```
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform
to the GitLab EE API.
......@@ -827,8 +903,7 @@ Example response:
}
```
Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see
the `weight` parameter:
Issues created by users on GitLab Premium or higher include the `weight` property:
```json
{
......@@ -839,10 +914,9 @@ the `weight` parameter:
}
```
Users of [GitLab Premium](https://about.gitlab.com/pricing/) can also see
the `epic` property:
Issues created by users on GitLab Premium or higher include the `epic` property:
```javascript
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
......@@ -854,7 +928,7 @@ the `epic` property:
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
// ...
...
}
```
......@@ -885,6 +959,8 @@ the issue still exists.
## New issue
> Moved `weight` to [GitLab Premium](https://about.gitlab.com/pricing/) due to Starter/Bronze being [discontinued](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) in 13.9.
Creates a new project issue.
```plaintext
......@@ -908,7 +984,7 @@ POST /projects/:id/issues
| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This fills out the issue with a default description and mark all discussions as resolved. When passing a description or title, these values take precedence over the default values.|
| `milestone_id` | integer | no | The global ID of a milestone to assign issue |
| `title` | string | yes | The title of an issue |
| `weight` **(STARTER)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. |
| `weight` **(PREMIUM)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug"
......@@ -975,8 +1051,7 @@ Example response:
}
```
Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see
the `weight` parameter:
Issues created by users on GitLab Premium or higher include the `weight` property:
```json
{
......@@ -987,8 +1062,25 @@ the `weight` parameter:
}
```
Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see
the `health_status` parameter:
Issues created by users on GitLab Premium or higher include the `epic` property:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"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
},
...
}
```
Issues created by users on GitLab Ultimate include the `health_status` property:
```json
[
......@@ -1004,6 +1096,10 @@ the `health_status` parameter:
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157).
Please use `iid` of the `epic` attribute instead.
NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
......@@ -1015,6 +1111,8 @@ See [Issues rate limits](../user/admin_area/settings/rate_limit_on_issues_creati
## Edit issue
> Moved `weight` to [GitLab Premium](https://about.gitlab.com/pricing/) due to Starter/Bronze being [discontinued](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) in 13.9.
Updates an existing project issue. This call is also used to mark an issue as
closed.
......@@ -1054,7 +1152,7 @@ PUT /projects/:id/issues/:issue_iid
| `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it |
| `title` | string | no | The title of an issue |
| `updated_at` | string | no | When the issue was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires administrator or project owner rights). Empty string or null values are not accepted.|
| `weight` **(STARTER)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0 |
| `weight` **(PREMIUM)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0 |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close"
......@@ -1128,8 +1226,7 @@ Example response:
}
```
Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see
the `weight` parameter:
Issues created by users on GitLab Premium or higher include the `weight` property:
```json
{
......@@ -1140,8 +1237,25 @@ the `weight` parameter:
}
```
Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see
the `health_status` parameter:
Issues created by users on GitLab Premium or higher include the `epic` property:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"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
},
...
}
```
Issues created by users on GitLab Ultimate include the `health_status` property:
```json
[
......@@ -1158,6 +1272,10 @@ NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157).
Please use `iid` of the `epic` attribute instead.
WARNING:
`assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
......@@ -1293,8 +1411,7 @@ Example response:
}
```
Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see
the `weight` parameter:
Issues created by users on GitLab Premium or higher include the `weight` property:
```json
{
......@@ -1305,8 +1422,25 @@ the `weight` parameter:
}
```
Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see
the `health_status` parameter:
Issues created by users on GitLab Premium or higher include the `epic` property:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"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
},
...
}
```
Issues created by users on GitLab Ultimate include the `health_status` property:
```json
[
......@@ -1322,6 +1456,10 @@ the `health_status` parameter:
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157).
Please use `iid` of the `epic` attribute instead.
NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
......@@ -1416,8 +1554,7 @@ Example response:
}
```
Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see
the `weight` parameter:
Issues created by users on GitLab Premium or higher include the `weight` property:
```json
{
......@@ -1428,9 +1565,44 @@ the `weight` parameter:
}
```
Issues created by users on GitLab Premium or higher include the `epic` property:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"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
},
...
}
```
Issues created by users on GitLab Ultimate include the `health_status` property:
```json
[
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"health_status": "on_track",
...
}
]
```
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157).
Please use `iid` of the `epic` attribute instead.
NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7