Skip to content
Snippets Groups Projects
Commit ebaedca9 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files

Merge branch 'doc_refactor_issues_api' into 'master' 

Refactor issues API documentation



See merge request !2466
parents 9f095bbb 13f52de0
No related branches found
No related tags found
No related merge requests found
Pipeline #
Show whitespace changes
Inline Side-by-side
Showing
with 260 additions and 144 deletions
doc/api/issues.md
+ 260
− 144
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,
"title": "4xx/5xx pages",
"description": "",
"labels": [],
"milestone": null,
"assignee": null,
"author" : { "author" : {
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"state" : "active", "state" : "active",
"created_at": "2012-05-23T08:00:58Z" "id" : 18,
"web_url" : "https://gitlab.example.com/u/eileen.lowe",
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"username" : "eileen.lowe"
}, },
"state": "closed",
"updated_at": "2012-07-02T17:53:12Z",
"created_at": "2012-07-02T17:53:12Z"
},
{
"id": 42,
"iid": 4,
"project_id": 8,
"title": "Add user settings",
"description": "",
"labels": [
"feature"
],
"milestone" : { "milestone" : {
"id": 1, "project_id" : 1,
"title": "v1.0", "description" : "Ducimus nam enim ex consequatur cumque ratione.",
"description": "", "state" : "closed",
"due_date": "2012-07-20", "due_date" : null,
"state": "reopened", "iid" : 2,
"updated_at": "2012-07-04T13:42:48Z", "created_at" : "2016-01-04T15:31:39.996Z",
"created_at": "2012-07-04T13:42:48Z" "title" : "v4.0",
"id" : 17,
"updated_at" : "2016-01-04T15:31:39.996Z"
}, },
"project_id" : 1,
"assignee" : { "assignee" : {
"id": 2,
"username": "jack_smith",
"email": "jack@example.com",
"name": "Jack Smith",
"state" : "active", "state" : "active",
"created_at": "2012-05-23T08:01:01Z"
},
"author": {
"id" : 1, "id" : 1,
"username": "john_smith", "name" : "Administrator",
"email": "john@example.com", "web_url" : "https://gitlab.example.com/u/root",
"name": "John Smith", "avatar_url" : null,
"state": "active", "username" : "root"
"created_at": "2012-05-23T08:00:58Z" },
"updated_at" : "2016-01-04T15:31:51.081Z",
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"iid" : 6,
"labels" : []
}, },
"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 |
```bash
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues/41
```
   
- `id` (required) - The ID of a project Example response:
- `issue_id` (required) - The ID of a project issue
   
```json ```json
{ {
"id": 42, "project_id" : 4,
"iid": 3,
"project_id": 8,
"title": "Add user settings",
"description": "",
"labels": [
"feature"
],
"milestone" : { "milestone" : {
"id": 1, "due_date" : null,
"title": "v1.0", "project_id" : 4,
"description": "",
"due_date": "2012-07-20",
"state" : "closed", "state" : "closed",
"updated_at": "2012-07-04T13:42:48Z", "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
"created_at": "2012-07-04T13:42:48Z" "iid" : 3,
}, "id" : 11,
"assignee": { "title" : "v3.0",
"id": 2, "created_at" : "2016-01-04T15:31:39.788Z",
"username": "jack_smith", "updated_at" : "2016-01-04T15:31:39.788Z"
"email": "jack@example.com",
"name": "Jack Smith",
"state": "active",
"created_at": "2012-05-23T08:01:01Z"
}, },
"author" : { "author" : {
"state" : "active",
"web_url" : "https://gitlab.example.com/u/root",
"avatar_url" : null,
"username" : "root",
"id" : 1, "id" : 1,
"username": "john_smith", "name" : "Administrator"
"email": "john@example.com", },
"name": "John Smith", "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", "state" : "active",
"created_at": "2012-05-23T08:00:58Z" "username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}, },
"state": "opened", "labels" : [],
"updated_at": "2012-07-12T13:43:19Z", "id" : 41,
"created_at": "2012-06-28T12:58:06Z" "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"
} }
``` ```
   
@@ -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.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment