Add todos API documentation and changelog

4 files changed, 220 insertions, 3 deletions

diff --git a/CHANGELOG b/CHANGELOG
index 4b754c2aba3..98d23ea6824 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -19,6 +19,7 @@ v 8.10.0 (unreleased)
   - Fix changing issue state columns in milestone view
   - Add notification settings dropdown for groups
   - Allow importing from Github using Personal Access Tokens. (Eric K Idema)
+  - API: Todos !3188 (Robert Schilling)
   - Fix user creation with stronger minimum password requirements !4054 (nathan-pmt)
   - PipelinesFinder uses git cache data
   - Check for conflicts with existing Project's wiki path when creating a new project.
diff --git a/doc/api/README.md b/doc/api/README.md
index 288f7f9ee69..d1e6c54c521 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -36,6 +36,7 @@ following locations:
 - [System Hooks](system_hooks.md)
 - [Tags](tags.md)
 - [Users](users.md)
+- [Todos](todos.md)
 
 ### Internal CI API
 
diff --git a/doc/api/todos.md b/doc/api/todos.md
new file mode 100644
index 00000000000..1d38e4acf13
--- /dev/null
+++ b/doc/api/todos.md
@@ -0,0 +1,217 @@
+# Todos
+
+**Note:** This feature was [introduced][ce-3188] in GitLab 8.10
+
+## Get a list of todos
+
+Returns a list of todos. When no filter is applied, it returns all pending todos
+for the current user. Different filters allow the user to
+
+```
+GET /todos
+```
+
+Parameters:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `action_id` | integer | no | The ID of the action of the todo. See the table below for the ID mapping |
+| `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` |
+| `type` | string | no | The type of an todo. Can be either `Issue` or `MergeRequest` |
+
+| `action_id` | Action |
+| ----------- | ------ |
+| 1           | Issuable assigned |
+| 2           | Mentioned in issuable |
+| 3           | Build failed |
+| 4           | Todo marked for you |
+
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/todos
+```
+
+Example Response:
+
+```json
+[
+  {
+    "id": 130,
+    "project": {
+      "id": 1,
+      "name": "Underscore",
+      "name_with_namespace": "Documentcloud / Underscore",
+      "path": "underscore",
+      "path_with_namespace": "documentcloud/underscore"
+    },
+    "author": {
+      "name": "Juwan Abbott",
+      "username": "halle",
+      "id": 8,
+      "state": "active",
+      "avatar_url": "http://www.gravatar.com/avatar/a0086c7b9e0d73312f32ff745fdcb43e?s=80&d=identicon",
+      "web_url": "https://gitlab.example.com/u/halle"
+    },
+    "action_name": "assigned",
+    "target_id": 71,
+    "target_type": "Issue",
+    "target_reference": "#1",
+    "target_url": "https://gitlab.example.com/documentcloud/underscore/issues/1",
+    "body": "At voluptas qui nulla soluta qui et.",
+    "state": "pending",
+    "created_at": "2016-05-20T20:52:00.626Z"
+  },
+  {
+    "id": 129,
+    "project": {
+      "id": 1,
+      "name": "Underscore",
+      "name_with_namespace": "Documentcloud / Underscore",
+      "path": "underscore",
+      "path_with_namespace": "documentcloud/underscore"
+    },
+    "author": {
+      "name": "Juwan Abbott",
+      "username": "halle",
+      "id": 8,
+      "state": "active",
+      "avatar_url": "http://www.gravatar.com/avatar/a0086c7b9e0d73312f32ff745fdcb43e?s=80&d=identicon",
+      "web_url": "https://gitlab.example.com/u/halle"
+    },
+    "action_name": "mentioned",
+    "target_id": 79,
+    "target_type": "Issue",
+    "target_reference": "#9",
+    "target_url": "https://gitlab.example.com/documentcloud/underscore/issues/9#note_959",
+    "body": "@root Fix this shit",
+    "state": "pending",
+    "created_at": "2016-05-20T20:51:51.503Z"
+  }
+]
+```
+
+## Mark a todo as done
+
+Marks a single pending todo given by its ID for the current user as done. The to
+marked as done is returned in the response.
+
+```
+DELETE /todos/:id
+```
+
+Parameters:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a todo |
+
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/todos/130
+```
+
+Example Response:
+
+```json
+{
+  "id": 130,
+  "project": {
+    "id": 1,
+    "name": "Underscore",
+    "name_with_namespace": "Documentcloud / Underscore",
+    "path": "underscore",
+    "path_with_namespace": "documentcloud/underscore"
+  },
+  "author": {
+    "name": "Juwan Abbott",
+    "username": "halle",
+    "id": 8,
+    "state": "active",
+    "avatar_url": "http://www.gravatar.com/avatar/a0086c7b9e0d73312f32ff745fdcb43e?s=80&d=identicon",
+    "web_url": "https://gitlab.example.com/u/halle"
+  },
+  "action_name": "assigned",
+  "target_id": 71,
+  "target_type": "Issue",
+  "target_reference": "#1",
+  "target_url": "https://gitlab.example.com/documentcloud/underscore/issues/1",
+  "body": "At voluptas qui nulla soluta qui et.",
+  "state": "done",
+  "created_at": "2016-05-20T20:52:00.626Z"
+}
+```
+
+## Mark all todos as done
+
+Marks all pending todos for the current user as done. All todos marked as done
+are returned in the response.
+
+```
+DELETE /todos
+```
+
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/todos
+```
+
+Example Response:
+
+```json
+[
+  {
+    "id": 130,
+    "project": {
+      "id": 1,
+      "name": "Underscore",
+      "name_with_namespace": "Documentcloud / Underscore",
+      "path": "underscore",
+      "path_with_namespace": "documentcloud/underscore"
+    },
+    "author": {
+      "name": "Juwan Abbott",
+      "username": "halle",
+      "id": 8,
+      "state": "active",
+      "avatar_url": "http://www.gravatar.com/avatar/a0086c7b9e0d73312f32ff745fdcb43e?s=80&d=identicon",
+      "web_url": "https://gitlab.example.com/u/halle"
+    },
+    "action_name": "assigned",
+    "target_id": 71,
+    "target_type": "Issue",
+    "target_reference": "#1",
+    "target_url": "https://gitlab.example.com/documentcloud/underscore/issues/1",
+    "body": "At voluptas qui nulla soluta qui et.",
+    "state": "done",
+    "created_at": "2016-05-20T20:52:00.626Z"
+  },
+  {
+    "id": 129,
+    "project": {
+      "id": 1,
+      "name": "Underscore",
+      "name_with_namespace": "Documentcloud / Underscore",
+      "path": "underscore",
+      "path_with_namespace": "documentcloud/underscore"
+    },
+    "author": {
+      "name": "Juwan Abbott",
+      "username": "halle",
+      "id": 8,
+      "state": "active",
+      "avatar_url": "http://www.gravatar.com/avatar/a0086c7b9e0d73312f32ff745fdcb43e?s=80&d=identicon",
+      "web_url": "https://gitlab.example.com/u/halle"
+    },
+    "action_name": "mentioned",
+    "target_id": 79,
+    "target_type": "Issue",
+    "target_reference": "#9",
+    "target_url": "https://gitlab.example.com/documentcloud/underscore/issues/9#note_959",
+    "body": "@root Fix this shit",
+    "state": "done",
+    "created_at": "2016-05-20T20:51:51.503Z"
+  }
+]
+```
+
+[ce-3188]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3188
diff --git a/lib/api/todos.rb b/lib/api/todos.rb
index 10fd2aac092..67714a796c7 100644
--- a/lib/api/todos.rb
+++ b/lib/api/todos.rb
@@ -21,13 +21,12 @@ module API
         present paginate(todos), with: Entities::Todo
       end
 
-      # Mark todo as done
+      # Mark a todo as done
       #
       # Parameters:
       #   id: (required) - The ID of the todo being marked as done
       #
       # Example Request:
-      #
       #  DELETE /todos/:id
       #
       delete ':id' do
@@ -40,7 +39,6 @@ module API
       # Mark all todos as done
       #
       # Example Request:
-      #
       #  DELETE /todos
       #
       delete do