Skip to content

G
gitlab-ce
Commit ebaedca9 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Merge branch 'doc_refactor_issues_api' into 'master' 

Refactor issues API documentation



See merge request !2466
parents 9f095bbb 13f52de0
Hide whitespace changes
Inline Side-by-side
Showing with 260 additions and 144 deletions
doc/api/issues.md
View file @ ebaedca9
# Issues # Issues
Every API call to issues must be authenticated.
If a user is not a member of a project and the project is private, a `GET`
request on that project will result to a `404` status code.
## Issues pagination
By default, `GET` requests return 20 results at a time because the API results
are paginated.
Read more on [pagination](README.md#pagination).
## List issues ## List issues
Get all issues created by authenticated user. This function takes pagination parameters Get all issues created by the authenticated user.
`page` and `per_page` to restrict the list of issues.
``` ```
GET /issues GET /issues
...@@ -14,81 +25,65 @@ GET /issues?labels=foo,bar ...@@ -14,81 +25,65 @@ GET /issues?labels=foo,bar
GET /issues?labels=foo,bar&state=opened GET /issues?labels=foo,bar&state=opened
``` ```
Parameters: | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `state` | string | no | Return all issues or just those that are `opened` or `closed`|
| `labels` | string | no | Comma-separated list of label names |
| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` |
```bash
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/issues
```
- `state` (optional) - Return `all` issues or just those that are `opened` or `closed` Example response:
- `labels` (optional) - Comma-separated list of label names
- `order_by` (optional) - Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`
- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
```json ```json
[ [
{ {
"id": 43, "state" : "opened",
"iid": 3, "description" : "Ratione dolores corrupti mollitia soluta quia.",
"project_id": 8, "author" : {
"title": "4xx/5xx pages", "state" : "active",
"description": "", "id" : 18,
"labels": [], "web_url" : "https://gitlab.example.com/u/eileen.lowe",
"milestone": null, "name" : "Alexandra Bashirian",
"assignee": null, "avatar_url" : null,
"author": { "username" : "eileen.lowe"
"id": 1, },
"username": "john_smith", "milestone" : {
"email": "john@example.com", "project_id" : 1,
"name": "John Smith", "description" : "Ducimus nam enim ex consequatur cumque ratione.",
"state": "active", "state" : "closed",
"created_at": "2012-05-23T08:00:58Z" "due_date" : null,
}, "iid" : 2,
"state": "closed", "created_at" : "2016-01-04T15:31:39.996Z",
"updated_at": "2012-07-02T17:53:12Z", "title" : "v4.0",
"created_at": "2012-07-02T17:53:12Z" "id" : 17,
}, "updated_at" : "2016-01-04T15:31:39.996Z"
{ },
"id": 42, "project_id" : 1,
"iid": 4, "assignee" : {
"project_id": 8, "state" : "active",
"title": "Add user settings", "id" : 1,
"description": "", "name" : "Administrator",
"labels": [ "web_url" : "https://gitlab.example.com/u/root",
"feature" "avatar_url" : null,
], "username" : "root"
"milestone": { },
"id": 1, "updated_at" : "2016-01-04T15:31:51.081Z",
"title": "v1.0", "id" : 76,
"description": "", "title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"due_date": "2012-07-20", "created_at" : "2016-01-04T15:31:51.081Z",
"state": "reopened", "iid" : 6,
"updated_at": "2012-07-04T13:42:48Z", "labels" : []
"created_at": "2012-07-04T13:42:48Z" },
},
"assignee": {
"id": 2,
"username": "jack_smith",
"email": "jack@example.com",
"name": "Jack Smith",
"state": "active",
"created_at": "2012-05-23T08:01:01Z"
},
"author": {
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"state": "active",
"created_at": "2012-05-23T08:00:58Z"
},
"state": "opened",
"updated_at": "2012-07-12T13:43:19Z",
"created_at": "2012-06-28T12:58:06Z"
}
] ]
``` ```
## List project issues ## List project issues
Get a list of project issues. This function accepts pagination parameters `page` and `per_page` Get a list of a project's issues.
to return the list of project issues.
``` ```
GET /projects/:id/issues GET /projects/:id/issues
...@@ -102,67 +97,123 @@ GET /projects/:id/issues?milestone=1.0.0&state=opened ...@@ -102,67 +97,123 @@ GET /projects/:id/issues?milestone=1.0.0&state=opened
GET /projects/:id/issues?iid=42 GET /projects/:id/issues?iid=42
``` ```
Parameters: | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `iid` | integer | no | Return the issue having the given `iid` |
| `state` | string | no | Return all issues or just those that are `opened` or `closed`|
| `labels` | string | no | Comma-separated list of label names |
| `milestone` | string| no | The milestone title |
| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` |
```bash
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues
```
Example response:
- `id` (required) - The ID of a project ```json
- `iid` (optional) - Return the issue having the given `iid` [
- `state` (optional) - Return `all` issues or just those that are `opened` or `closed` {
- `labels` (optional) - Comma-separated list of label names "project_id" : 4,
- `milestone` (optional) - Milestone title "milestone" : {
- `order_by` (optional) - Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` "due_date" : null,
- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc` "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"
},
"author" : {
"state" : "active",
"web_url" : "https://gitlab.example.com/u/root",
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
"assignee" : {
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/u/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"labels" : [],
"id" : 41,
"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"
}
]
```
## Single issue ## Single issue
Gets a single project issue. Get a single project issue.
``` ```
GET /projects/:id/issues/:issue_id GET /projects/:id/issues/:issue_id
``` ```
Parameters: | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `issue_id`| integer | yes | The ID of a project's issue |
- `id` (required) - The ID of a project ```bash
- `issue_id` (required) - The ID of a project issue curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues/41
```
Example response:
```json ```json
{ {
"id": 42, "project_id" : 4,
"iid": 3, "milestone" : {
"project_id": 8, "due_date" : null,
"title": "Add user settings", "project_id" : 4,
"description": "", "state" : "closed",
"labels": [ "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
"feature" "iid" : 3,
], "id" : 11,
"milestone": { "title" : "v3.0",
"id": 1, "created_at" : "2016-01-04T15:31:39.788Z",
"title": "v1.0", "updated_at" : "2016-01-04T15:31:39.788Z"
"description": "", },
"due_date": "2012-07-20", "author" : {
"state": "closed", "state" : "active",
"updated_at": "2012-07-04T13:42:48Z", "web_url" : "https://gitlab.example.com/u/root",
"created_at": "2012-07-04T13:42:48Z" "avatar_url" : null,
}, "username" : "root",
"assignee": { "id" : 1,
"id": 2, "name" : "Administrator"
"username": "jack_smith", },
"email": "jack@example.com", "description" : "Omnis vero earum sunt corporis dolor et placeat.",
"name": "Jack Smith", "state" : "closed",
"state": "active", "iid" : 1,
"created_at": "2012-05-23T08:01:01Z" "assignee" : {
}, "avatar_url" : null,
"author": { "web_url" : "https://gitlab.example.com/u/lennie",
"id": 1, "state" : "active",
"username": "john_smith", "username" : "lennie",
"email": "john@example.com", "id" : 9,
"name": "John Smith", "name" : "Dr. Luella Kovacek"
"state": "active", },
"created_at": "2012-05-23T08:00:58Z" "labels" : [],
}, "id" : 41,
"state": "opened", "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
"updated_at": "2012-07-12T13:43:19Z", "updated_at" : "2016-01-04T15:31:46.176Z",
"created_at": "2012-06-28T12:58:06Z" "created_at" : "2016-01-04T15:31:46.176Z"
} }
``` ```
...@@ -170,57 +221,122 @@ Parameters: ...@@ -170,57 +221,122 @@ Parameters:
Creates a new project issue. Creates a new project issue.
If the operation is successful, a status code of `200` and the newly-created
issue is returned. If an error occurs, an error number and a message explaining
the reason is returned.
``` ```
POST /projects/:id/issues POST /projects/:id/issues
``` ```
Parameters: | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `title` | string | yes | The title of an issue |
| `description` | string | no | The description of an issue |
| `assignee_id` | integer | no | The ID of a user to assign issue |
| `milestone_id` | integer | no | The ID of a milestone to assign issue |
| `labels` | string | no | Comma-separated label names for an issue |
```bash
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues?title=Issues%20with%20auth&labels=bug
```
- `id` (required) - The ID of a project Example response:
- `title` (required) - The title of an issue
- `description` (optional) - The description of an issue
- `assignee_id` (optional) - The ID of a user to assign issue
- `milestone_id` (optional) - The ID of a milestone to assign issue
- `labels` (optional) - Comma-separated label names for an issue
If the operation is successful, 200 and the newly created issue is returned. ```json
If an error occurs, an error number and a message explaining the reason is returned. {
"project_id" : 4,
"id" : 84,
"created_at" : "2016-01-07T12:44:33.959Z",
"iid" : 14,
"title" : "Issues with auth",
"state" : "opened",
"assignee" : null,
"labels" : [
"bug"
],
"author" : {
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"state" : "active",
"web_url" : "https://gitlab.example.com/u/eileen.lowe",
"id" : 18,
"username" : "eileen.lowe"
},
"description" : null,
"updated_at" : "2016-01-07T12:44:33.959Z",
"milestone" : null
}
```
## Edit issue ## Edit issue
Updates an existing project issue. This function is also used to mark an issue as closed. Updates an existing project issue. This call is also used to mark an issue as
closed.
If the operation is successful, a code of `200` and the updated issue is
returned. If an error occurs, an error number and a message explaining the
reason is returned.
``` ```
PUT /projects/:id/issues/:issue_id PUT /projects/:id/issues/:issue_id
``` ```
Parameters: | 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 |
| `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 |
```bash
curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues/85?state_event=close
```
- `id` (required) - The ID of a project Example response:
- `issue_id` (required) - The ID of a project's issue
- `title` (optional) - The title of an issue
- `description` (optional) - The description of an issue
- `assignee_id` (optional) - The ID of a user to assign issue
- `milestone_id` (optional) - The ID of a milestone to assign issue
- `labels` (optional) - Comma-separated label names for an issue
- `state_event` (optional) - The state event of an issue ('close' to close issue and 'reopen' to reopen it)
If the operation is successful, 200 and the updated issue is returned. ```json
If an error occurs, an error number and a message explaining the reason is returned. {
"created_at" : "2016-01-07T12:46:01.410Z",
"author" : {
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"username" : "eileen.lowe",
"id" : 18,
"state" : "active",
"web_url" : "https://gitlab.example.com/u/eileen.lowe"
},
"state" : "closed",
"title" : "Issues with auth",
"project_id" : 4,
"description" : null,
"updated_at" : "2016-01-07T12:55:16.213Z",
"iid" : 15,
"labels" : [
"bug"
],
"id" : 85,
"assignee" : null,
"milestone" : null
}
```
## Delete existing issue (**Deprecated**) ## Delete existing issue (**Deprecated**)
The function is deprecated and returns a `405 Method Not Allowed` error if called. An issue gets now closed and is done by calling `PUT /projects/:id/issues/:issue_id` with parameter `state_event` set to `close`. This call is deprecated and returns a `405 Method Not Allowed` error if called.
An issue gets now closed and is done by calling
`PUT /projects/:id/issues/:issue_id` with the parameter `state_event` set to
`close`. See [edit issue](#edit-issue) for more details.
``` ```
DELETE /projects/:id/issues/:issue_id DELETE /projects/:id/issues/:issue_id
``` ```
Parameters:
- `id` (required) - The project ID
- `issue_id` (required) - The ID of the issue
## Comments on issues ## Comments on issues
Comments are done via the notes resource. Comments are done via the [notes](notes.md) resource.
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