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