BigW Consortium Gitlab

issues.md 5.39 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

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

## List project issues

88 89
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
90 91 92

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

Parameters:

104
- `id` (required) - The ID of a project
105
- `state` (optional) - Return `all` issues or just those that are `opened` or `closed`
106
- `labels` (optional) - Comma-separated list of label names
107
- `milestone` (optional) - Milestone title
108

Nihad Abbasov committed
109 110
## Single issue

111
Gets a single project issue.
Nihad Abbasov committed
112 113 114 115 116 117 118

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

Parameters:

119 120
- `id` (required) - The ID of a project
- `issue_id` (required) - The ID of a project issue
Nihad Abbasov committed
121 122 123 124

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

## New issue

165
Creates a new project issue.
Nihad Abbasov committed
166 167 168 169 170 171 172

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

Parameters:

173 174 175 176 177 178
- `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
179

180 181 182
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
183 184
## Edit issue

185
Updates an existing project issue. This function is also used to mark an issue as closed.
Nihad Abbasov committed
186 187 188 189 190 191 192

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

Parameters:

193 194 195 196 197 198 199 200
- `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)
201

202 203 204
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.

205 206
## Delete existing issue (**Deprecated**)

207
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 `closed` set to 1.
208 209 210 211 212 213 214

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

Parameters:

215 216
- `id` (required) - The project ID
- `issue_id` (required) - The ID of the issue
217 218 219 220

## Comments on issues

Comments are done via the notes resource.