BigW Consortium Gitlab

todos.md 9.45 KB
Newer Older
1
# Todos API
2

3
> [Introduced][ce-3188] in GitLab 8.10.
4 5 6 7

## Get a list of todos

Returns a list of todos. When no filter is applied, it returns all pending todos
8
for the current user. Different filters allow the user to precise the request.
9 10 11 12 13 14 15 16 17

```
GET /todos
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
18
| `action` | string | no | The action to be filtered. Can be `assigned`, `mentioned`, `build_failed`, `marked`, or `approval_required`. |
19 20 21
| `author_id` | integer | no | The ID of an author |
| `project_id` | integer | no | The ID of a project |
| `state` | string | no | The state of the todo. Can be either `pending` or `done` |
22
| `type` | string | no | The type of a todo. Can be either `Issue` or `MergeRequest` |
23 24

```bash
25
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/todos
26 27 28 29 30 31 32
```

Example Response:

```json
[
  {
33
    "id": 102,
34
    "project": {
35 36 37 38 39
      "id": 2,
      "name": "Gitlab Ce",
      "name_with_namespace": "Gitlab Org / Gitlab Ce",
      "path": "gitlab-ce",
      "path_with_namespace": "gitlab-org/gitlab-ce"
40 41
    },
    "author": {
42 43 44
      "name": "Administrator",
      "username": "root",
      "id": 1,
45
      "state": "active",
46
      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
47
      "web_url": "https://gitlab.example.com/root"
48
    },
49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
    "action_name": "marked",
    "target_type": "MergeRequest",
    "target": {
      "id": 34,
      "iid": 7,
      "project_id": 2,
      "title": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
      "description": "Et ea et omnis illum cupiditate. Dolor aspernatur tenetur ducimus facilis est nihil. Quo esse cupiditate molestiae illo corrupti qui quidem dolor.",
      "state": "opened",
      "created_at": "2016-06-17T07:49:24.419Z",
      "updated_at": "2016-06-17T07:52:43.484Z",
      "target_branch": "tutorials_git_tricks",
      "source_branch": "DNSBL_docs",
      "upvotes": 0,
      "downvotes": 0,
      "author": {
        "name": "Maxie Medhurst",
        "username": "craig_rutherford",
        "id": 12,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon",
70
        "web_url": "https://gitlab.example.com/craig_rutherford"
71 72 73 74 75 76 77
      },
      "assignee": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
78
        "web_url": "https://gitlab.example.com/root"
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
      },
      "source_project_id": 2,
      "target_project_id": 2,
      "labels": [],
      "work_in_progress": false,
      "milestone": {
        "id": 32,
        "iid": 2,
        "project_id": 2,
        "title": "v1.0",
        "description": "Assumenda placeat ea voluptatem voluptate qui.",
        "state": "active",
        "created_at": "2016-06-17T07:47:34.163Z",
        "updated_at": "2016-06-17T07:47:34.163Z",
        "due_date": null
      },
95
      "merge_when_pipeline_succeeds": false,
96 97 98 99 100 101
      "merge_status": "cannot_be_merged",
      "subscribed": true,
      "user_notes_count": 7
    },
    "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ce/merge_requests/7",
    "body": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
102
    "state": "pending",
103
    "created_at": "2016-06-17T07:52:35.225Z"
104 105
  },
  {
106
    "id": 98,
107
    "project": {
108 109 110 111 112
      "id": 2,
      "name": "Gitlab Ce",
      "name_with_namespace": "Gitlab Org / Gitlab Ce",
      "path": "gitlab-ce",
      "path_with_namespace": "gitlab-org/gitlab-ce"
113 114
    },
    "author": {
115 116 117
      "name": "Maxie Medhurst",
      "username": "craig_rutherford",
      "id": 12,
118
      "state": "active",
119
      "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon",
120
      "web_url": "https://gitlab.example.com/craig_rutherford"
121
    },
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
    "action_name": "assigned",
    "target_type": "MergeRequest",
    "target": {
      "id": 34,
      "iid": 7,
      "project_id": 2,
      "title": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
      "description": "Et ea et omnis illum cupiditate. Dolor aspernatur tenetur ducimus facilis est nihil. Quo esse cupiditate molestiae illo corrupti qui quidem dolor.",
      "state": "opened",
      "created_at": "2016-06-17T07:49:24.419Z",
      "updated_at": "2016-06-17T07:52:43.484Z",
      "target_branch": "tutorials_git_tricks",
      "source_branch": "DNSBL_docs",
      "upvotes": 0,
      "downvotes": 0,
      "author": {
        "name": "Maxie Medhurst",
        "username": "craig_rutherford",
        "id": 12,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon",
143
        "web_url": "https://gitlab.example.com/craig_rutherford"
144 145 146 147 148 149 150
      },
      "assignee": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
151
        "web_url": "https://gitlab.example.com/root"
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
      },
      "source_project_id": 2,
      "target_project_id": 2,
      "labels": [],
      "work_in_progress": false,
      "milestone": {
        "id": 32,
        "iid": 2,
        "project_id": 2,
        "title": "v1.0",
        "description": "Assumenda placeat ea voluptatem voluptate qui.",
        "state": "active",
        "created_at": "2016-06-17T07:47:34.163Z",
        "updated_at": "2016-06-17T07:47:34.163Z",
        "due_date": null
      },
168
      "merge_when_pipeline_succeeds": false,
169 170 171 172 173 174
      "merge_status": "cannot_be_merged",
      "subscribed": true,
      "user_notes_count": 7
    },
    "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ce/merge_requests/7",
    "body": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
175
    "state": "pending",
176
    "created_at": "2016-06-17T07:49:24.624Z"
177 178 179 180 181 182
  }
]
```

## Mark a todo as done

183 184
Marks a single pending todo given by its ID for the current user as done. The
todo marked as done is returned in the response.
185 186

```
187
POST /todos/:id/mark_as_done
188 189 190 191 192 193 194 195 196
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a todo |

```bash
197
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/todos/130/mark_as_done
198 199 200 201 202 203
```

Example Response:

```json
{
204 205 206 207 208 209 210 211 212 213 214 215 216 217
    "id": 102,
    "project": {
      "id": 2,
      "name": "Gitlab Ce",
      "name_with_namespace": "Gitlab Org / Gitlab Ce",
      "path": "gitlab-ce",
      "path_with_namespace": "gitlab-org/gitlab-ce"
    },
    "author": {
      "name": "Administrator",
      "username": "root",
      "id": 1,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
218
      "web_url": "https://gitlab.example.com/root"
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240
    },
    "action_name": "marked",
    "target_type": "MergeRequest",
    "target": {
      "id": 34,
      "iid": 7,
      "project_id": 2,
      "title": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
      "description": "Et ea et omnis illum cupiditate. Dolor aspernatur tenetur ducimus facilis est nihil. Quo esse cupiditate molestiae illo corrupti qui quidem dolor.",
      "state": "opened",
      "created_at": "2016-06-17T07:49:24.419Z",
      "updated_at": "2016-06-17T07:52:43.484Z",
      "target_branch": "tutorials_git_tricks",
      "source_branch": "DNSBL_docs",
      "upvotes": 0,
      "downvotes": 0,
      "author": {
        "name": "Maxie Medhurst",
        "username": "craig_rutherford",
        "id": 12,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon",
241
        "web_url": "https://gitlab.example.com/craig_rutherford"
242 243 244 245 246 247 248
      },
      "assignee": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
249
        "web_url": "https://gitlab.example.com/root"
250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265
      },
      "source_project_id": 2,
      "target_project_id": 2,
      "labels": [],
      "work_in_progress": false,
      "milestone": {
        "id": 32,
        "iid": 2,
        "project_id": 2,
        "title": "v1.0",
        "description": "Assumenda placeat ea voluptatem voluptate qui.",
        "state": "active",
        "created_at": "2016-06-17T07:47:34.163Z",
        "updated_at": "2016-06-17T07:47:34.163Z",
        "due_date": null
      },
266
      "merge_when_pipeline_succeeds": false,
267 268 269 270 271 272 273 274
      "merge_status": "cannot_be_merged",
      "subscribed": true,
      "user_notes_count": 7
    },
    "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ce/merge_requests/7",
    "body": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
    "state": "done",
    "created_at": "2016-06-17T07:52:35.225Z"
275 276 277 278 279
}
```

## Mark all todos as done

280
Marks all pending todos for the current user as done. It returns the HTTP status code `204` with an empty response.
281 282

```
283
POST /todos/mark_as_done
284 285 286
```

```bash
287
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/todos/donmark_as_donee
288 289 290 291
```


[ce-3188]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3188