BigW Consortium Gitlab

issues.md 5.8 KB
Newer Older
1 2
# Issues

Nihad Abbasov committed
3 4
## List issues

Johannes Schleifenbaum committed
5
Get all issues created by authenticated user. This function takes pagination parameters
6
`page` and `per_page` to restrict the list of issues.
Nihad Abbasov committed
7 8 9

```
GET /issues
10 11
GET /issues?state=opened
GET /issues?state=closed
12 13 14
GET /issues?labels=foo
GET /issues?labels=foo,bar
GET /issues?labels=foo,bar&state=opened
Nihad Abbasov committed
15 16
```

17 18 19
Parameters:

- `state` (optional) - Return `all` issues or just those that are `opened` or `closed`
20
- `labels` (optional) - Comma-separated list of label names
21 22
- `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`
23

Nihad Abbasov committed
24 25 26 27
```json
[
  {
    "id": 43,
Dmitriy Zaporozhets committed
28
    "iid": 3,
29
    "project_id": 8,
Nihad Abbasov committed
30 31
    "title": "4xx/5xx pages",
    "description": "",
32
    "labels": [],
Nihad Abbasov committed
33 34 35 36
    "milestone": null,
    "assignee": null,
    "author": {
      "id": 1,
37
      "username": "john_smith",
Nihad Abbasov committed
38 39
      "email": "john@example.com",
      "name": "John Smith",
40
      "state": "active",
Nihad Abbasov committed
41 42
      "created_at": "2012-05-23T08:00:58Z"
    },
43
    "state": "closed",
Nihad Abbasov committed
44 45 46 47 48
    "updated_at": "2012-07-02T17:53:12Z",
    "created_at": "2012-07-02T17:53:12Z"
  },
  {
    "id": 42,
Dmitriy Zaporozhets committed
49
    "iid": 4,
50
    "project_id": 8,
Nihad Abbasov committed
51 52 53 54 55 56 57 58 59 60
    "title": "Add user settings",
    "description": "",
    "labels": [
      "feature"
    ],
    "milestone": {
      "id": 1,
      "title": "v1.0",
      "description": "",
      "due_date": "2012-07-20",
61
      "state": "reopened",
Nihad Abbasov committed
62 63 64 65 66
      "updated_at": "2012-07-04T13:42:48Z",
      "created_at": "2012-07-04T13:42:48Z"
    },
    "assignee": {
      "id": 2,
67
      "username": "jack_smith",
Nihad Abbasov committed
68 69
      "email": "jack@example.com",
      "name": "Jack Smith",
70
      "state": "active",
Nihad Abbasov committed
71 72 73 74
      "created_at": "2012-05-23T08:01:01Z"
    },
    "author": {
      "id": 1,
75
      "username": "john_smith",
Nihad Abbasov committed
76 77
      "email": "john@example.com",
      "name": "John Smith",
78
      "state": "active",
Nihad Abbasov committed
79 80
      "created_at": "2012-05-23T08:00:58Z"
    },
81
    "state": "opened",
Nihad Abbasov committed
82 83 84 85 86 87 88 89
    "updated_at": "2012-07-12T13:43:19Z",
    "created_at": "2012-06-28T12:58:06Z"
  }
]
```

## List project issues

90 91
Get a list of project issues. This function accepts pagination parameters `page` and `per_page`
to return the list of project issues.
Nihad Abbasov committed
92 93 94

```
GET /projects/:id/issues
95 96
GET /projects/:id/issues?state=opened
GET /projects/:id/issues?state=closed
97 98 99
GET /projects/:id/issues?labels=foo
GET /projects/:id/issues?labels=foo,bar
GET /projects/:id/issues?labels=foo,bar&state=opened
100 101
GET /projects/:id/issues?milestone=1.0.0
GET /projects/:id/issues?milestone=1.0.0&state=opened
Nihad Abbasov committed
102 103 104 105
```

Parameters:

106
- `id` (required) - The ID of a project
107
- `state` (optional) - Return `all` issues or just those that are `opened` or `closed`
108
- `labels` (optional) - Comma-separated list of label names
109
- `milestone` (optional) - Milestone title
110 111
- `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`
112

Nihad Abbasov committed
113 114
## Single issue

115
Gets a single project issue.
Nihad Abbasov committed
116 117 118 119 120 121 122

```
GET /projects/:id/issues/:issue_id
```

Parameters:

123 124
- `id` (required) - The ID of a project
- `issue_id` (required) - The ID of a project issue
Nihad Abbasov committed
125 126 127 128

```json
{
  "id": 42,
Dmitriy Zaporozhets committed
129
  "iid": 3,
130
  "project_id": 8,
Nihad Abbasov committed
131 132 133 134 135 136 137 138 139 140
  "title": "Add user settings",
  "description": "",
  "labels": [
    "feature"
  ],
  "milestone": {
    "id": 1,
    "title": "v1.0",
    "description": "",
    "due_date": "2012-07-20",
141
    "state": "closed",
Nihad Abbasov committed
142 143 144 145 146
    "updated_at": "2012-07-04T13:42:48Z",
    "created_at": "2012-07-04T13:42:48Z"
  },
  "assignee": {
    "id": 2,
147
    "username": "jack_smith",
Nihad Abbasov committed
148 149
    "email": "jack@example.com",
    "name": "Jack Smith",
150
    "state": "active",
Nihad Abbasov committed
151 152 153 154
    "created_at": "2012-05-23T08:01:01Z"
  },
  "author": {
    "id": 1,
155
    "username": "john_smith",
Nihad Abbasov committed
156 157
    "email": "john@example.com",
    "name": "John Smith",
158
    "state": "active",
Nihad Abbasov committed
159 160
    "created_at": "2012-05-23T08:00:58Z"
  },
161
  "state": "opened",
Nihad Abbasov committed
162 163 164 165 166 167 168
  "updated_at": "2012-07-12T13:43:19Z",
  "created_at": "2012-06-28T12:58:06Z"
}
```

## New issue

169
Creates a new project issue.
Nihad Abbasov committed
170 171 172 173 174 175 176

```
POST /projects/:id/issues
```

Parameters:

177 178 179 180 181 182
- `id` (required) - The ID of a project
- `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
Nihad Abbasov committed
183

184 185 186
If the operation is successful, 200 and the newly created issue is returned.
If an error occurs, an error number and a message explaining the reason is returned.

Nihad Abbasov committed
187 188
## Edit issue

189
Updates an existing project issue. This function is also used to mark an issue as closed.
Nihad Abbasov committed
190 191 192 193 194 195 196

```
PUT /projects/:id/issues/:issue_id
```

Parameters:

197 198 199 200 201 202 203 204
- `id` (required) - The ID of a project
- `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)
205

206 207 208
If the operation is successful, 200 and the updated issue is returned.
If an error occurs, an error number and a message explaining the reason is returned.

209 210
## Delete existing issue (**Deprecated**)

211
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`.
212 213 214 215 216 217 218

```
DELETE /projects/:id/issues/:issue_id
```

Parameters:

219 220
- `id` (required) - The project ID
- `issue_id` (required) - The ID of the issue
221 222 223 224

## Comments on issues

Comments are done via the notes resource.