diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api/README.md | 1 | ||||
| -rw-r--r-- | doc/api/events.md | 347 | ||||
| -rw-r--r-- | doc/api/projects.md | 138 | ||||
| -rw-r--r-- | doc/api/users.md | 141 |
4 files changed, 350 insertions, 277 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 44e345b1cf6..e1d4009dedc 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -16,6 +16,7 @@ following locations: - [Deployments](deployments.md) - [Deploy Keys](deploy_keys.md) - [Environments](environments.md) +- [Events](events.md) - [Gitignores templates](templates/gitignores.md) - [GitLab CI Config templates](templates/gitlab_ci_ymls.md) - [Groups](groups.md) diff --git a/doc/api/events.md b/doc/api/events.md new file mode 100644 index 00000000000..ef57287264d --- /dev/null +++ b/doc/api/events.md @@ -0,0 +1,347 @@ +# Events + +## Filter parameters + +### Action Types + +Available action types for the `action` parameter are: + +- `created` +- `updated` +- `closed` +- `reopened` +- `pushed` +- `commented` +- `merged` +- `joined` +- `left` +- `destroyed` +- `expired` + +Note that these options are downcased. + +### Target Types + +Available target types for the `target_type` parameter are: + +- `issue` +- `milestone` +- `merge_request` +- `note` +- `project` +- `snippet` +- `user` + +Note that these options are downcased. + +### Date formatting + +Dates for the `before` and `after` parameters should be supplied in the following format: + +``` +YYYY-MM-DD +``` + +## List currently authenticated user's events + +>**Note:** This endpoint was introduced in GitLab 9.3. + +Get a list of events for the authenticated user. + +``` +GET /events +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `action` | string | no | Include only events of a particular [action type][action-types] | +| `target_type` | string | no | Include only events of a particular [target type][target-types] | +| `before` | date | no | Include only events created before a particular date. Please see [here for the supported format][date-formatting] | +| `after` | date | no | Include only events created after a particular date. Please see [here for the supported format][date-formatting] | +| `sort` | string | no | Sort events in `asc` or `desc` order by `created_at`. Default is `desc` | + +Example request: + +``` +curl --header "PRIVATE-TOKEN 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/events&target_type=issue&action=created&after=2017-01-31&before=2017-03-01 +``` + +Example response: + +```json +[ + { + "title":null, + "project_id":1, + "action_name":"opened", + "target_id":160, + "target_type":"Issue", + "author_id":25, + "data":null, + "target_title":"Qui natus eos odio tempore et quaerat consequuntur ducimus cupiditate quis.", + "created_at":"2017-02-09T10:43:19.667Z", + "author":{ + "name":"User 3", + "username":"user3", + "id":25, + "state":"active", + "avatar_url":"http://www.gravatar.com/avatar/97d6d9441ff85fdc730e02a6068d267b?s=80\u0026d=identicon", + "web_url":"https://gitlab.example.com/user3" + }, + "author_username":"user3" + }, + { + "title":null, + "project_id":1, + "action_name":"opened", + "target_id":159, + "target_type":"Issue", + "author_id":21, + "data":null, + "target_title":"Nostrum enim non et sed optio illo deleniti non.", + "created_at":"2017-02-09T10:43:19.426Z", + "author":{ + "name":"Test User", + "username":"ted", + "id":21, + "state":"active", + "avatar_url":"http://www.gravatar.com/avatar/80fb888c9a48b9a3f87477214acaa63f?s=80\u0026d=identicon", + "web_url":"https://gitlab.example.com/ted" + }, + "author_username":"ted" + } +] +``` + +### Get user contribution events + +>**Note:** Documentation was formerly located in the [Users API pages][users-api]. + +Get the contribution events for the specified user, sorted from newest to oldest. + +``` +GET /users/:id/events +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the user | +| `action` | string | no | Include only events of a particular [action type][action-types] | +| `target_type` | string | no | Include only events of a particular [target type][target-types] | +| `before` | date | no | Include only events created before a particular date. Please see [here for the supported format][date-formatting] | +| `after` | date | no | Include only events created after a particular date. Please see [here for the supported format][date-formatting] | +| `sort` | string | no | Sort events in `asc` or `desc` order by `created_at`. Default is `desc` | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/:id/events +``` + +Example response: + +```json +[ + { + "title": null, + "project_id": 15, + "action_name": "closed", + "target_id": 830, + "target_type": "Issue", + "author_id": 1, + "data": null, + "target_title": "Public project search field", + "author": { + "name": "Dmitriy Zaporozhets", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", + "web_url": "http://localhost:3000/root" + }, + "author_username": "root" + }, + { + "title": null, + "project_id": 15, + "action_name": "opened", + "target_id": null, + "target_type": null, + "author_id": 1, + "author": { + "name": "Dmitriy Zaporozhets", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", + "web_url": "http://localhost:3000/root" + }, + "author_username": "john", + "data": { + "before": "50d4420237a9de7be1304607147aec22e4a14af7", + "after": "c5feabde2d8cd023215af4d2ceeb7a64839fc428", + "ref": "refs/heads/master", + "user_id": 1, + "user_name": "Dmitriy Zaporozhets", + "repository": { + "name": "gitlabhq", + "url": "git@dev.gitlab.org:gitlab/gitlabhq.git", + "description": "GitLab: self hosted Git management software. \r\nDistributed under the MIT License.", + "homepage": "https://dev.gitlab.org/gitlab/gitlabhq" + }, + "commits": [ + { + "id": "c5feabde2d8cd023215af4d2ceeb7a64839fc428", + "message": "Add simple search to projects in public area", + "timestamp": "2013-05-13T18:18:08+00:00", + "url": "https://dev.gitlab.org/gitlab/gitlabhq/commit/c5feabde2d8cd023215af4d2ceeb7a64839fc428", + "author": { + "name": "Dmitriy Zaporozhets", + "email": "dmitriy.zaporozhets@gmail.com" + } + } + ], + "total_commits_count": 1 + }, + "target_title": null + }, + { + "title": null, + "project_id": 15, + "action_name": "closed", + "target_id": 840, + "target_type": "Issue", + "author_id": 1, + "data": null, + "target_title": "Finish & merge Code search PR", + "author": { + "name": "Dmitriy Zaporozhets", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", + "web_url": "http://localhost:3000/root" + }, + "author_username": "root" + }, + { + "title": null, + "project_id": 15, + "action_name": "commented on", + "target_id": 1312, + "target_type": "Note", + "author_id": 1, + "data": null, + "target_title": null, + "created_at": "2015-12-04T10:33:58.089Z", + "note": { + "id": 1312, + "body": "What an awesome day!", + "attachment": null, + "author": { + "name": "Dmitriy Zaporozhets", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", + "web_url": "http://localhost:3000/root" + }, + "created_at": "2015-12-04T10:33:56.698Z", + "system": false, + "noteable_id": 377, + "noteable_type": "Issue" + }, + "author": { + "name": "Dmitriy Zaporozhets", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", + "web_url": "http://localhost:3000/root" + }, + "author_username": "root" + } +] +``` + +## List a Project's visible events + +>**Note:** This endpoint has been around longer than the others. Documentation was formerly located in the [Projects API pages][projects-api]. + +Get a list of visible events for a particular project. + +``` +GET /:project_id/events +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `action` | string | no | Include only events of a particular [action type][action-types] | +| `target_type` | string | no | Include only events of a particular [target type][target-types] | +| `before` | date | no | Include only events created before a particular date. Please see [here for the supported format][date-formatting] | +| `after` | date | no | Include only events created after a particular date. Please see [here for the supported format][date-formatting] | +| `sort` | string | no | Sort events in `asc` or `desc` order by `created_at`. Default is `desc` | + +Example request: + +``` +curl --header "PRIVATE-TOKEN 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:project_id/events&target_type=issue&action=created&after=2017-01-31&before=2017-03-01 +``` + +Example response: + +```json +[ + { + "title":null, + "project_id":1, + "action_name":"opened", + "target_id":160, + "target_type":"Issue", + "author_id":25, + "data":null, + "target_title":"Qui natus eos odio tempore et quaerat consequuntur ducimus cupiditate quis.", + "created_at":"2017-02-09T10:43:19.667Z", + "author":{ + "name":"User 3", + "username":"user3", + "id":25, + "state":"active", + "avatar_url":"http://www.gravatar.com/avatar/97d6d9441ff85fdc730e02a6068d267b?s=80\u0026d=identicon", + "web_url":"https://gitlab.example.com/user3" + }, + "author_username":"user3" + }, + { + "title":null, + "project_id":1, + "action_name":"opened", + "target_id":159, + "target_type":"Issue", + "author_id":21, + "data":null, + "target_title":"Nostrum enim non et sed optio illo deleniti non.", + "created_at":"2017-02-09T10:43:19.426Z", + "author":{ + "name":"Test User", + "username":"ted", + "id":21, + "state":"active", + "avatar_url":"http://www.gravatar.com/avatar/80fb888c9a48b9a3f87477214acaa63f?s=80\u0026d=identicon", + "web_url":"https://gitlab.example.com/ted" + }, + "author_username":"ted" + } +] +``` + +[target-types]: #target-types "Target Type parameter" +[action-types]: #action-types "Action Type parameter" +[date-formatting]: #date-formatting "Date Formatting guidance" +[projects-api]: projects.md "Projects API pages" +[users-api]: users.md "Users API pages" diff --git a/doc/api/projects.md b/doc/api/projects.md index 70cad8a6025..0debdcfae89 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -310,143 +310,7 @@ GET /projects/:id/users ### Get project events -Get the events for the specified project sorted from newest to oldest. This -endpoint can be accessed without authentication if the project is publicly -accessible. - -``` -GET /projects/:id/events -``` - -Parameters: - -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | - -```json -[ - { - "title": null, - "project_id": 15, - "action_name": "closed", - "target_id": 830, - "target_type": "Issue", - "author_id": 1, - "data": null, - "target_title": "Public project search field", - "author": { - "name": "Dmitriy Zaporozhets", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", - "web_url": "http://localhost:3000/root" - }, - "author_username": "root" - }, - { - "title": null, - "project_id": 15, - "action_name": "opened", - "target_id": null, - "target_type": null, - "author_id": 1, - "author": { - "name": "Dmitriy Zaporozhets", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", - "web_url": "http://localhost:3000/root" - }, - "author_username": "john", - "data": { - "before": "50d4420237a9de7be1304607147aec22e4a14af7", - "after": "c5feabde2d8cd023215af4d2ceeb7a64839fc428", - "ref": "refs/heads/master", - "user_id": 1, - "user_name": "Dmitriy Zaporozhets", - "repository": { - "name": "gitlabhq", - "url": "git@dev.gitlab.org:gitlab/gitlabhq.git", - "description": "GitLab: self hosted Git management software. \r\nDistributed under the MIT License.", - "homepage": "https://dev.gitlab.org/gitlab/gitlabhq" - }, - "commits": [ - { - "id": "c5feabde2d8cd023215af4d2ceeb7a64839fc428", - "message": "Add simple search to projects in public area", - "timestamp": "2013-05-13T18:18:08+00:00", - "url": "https://dev.gitlab.org/gitlab/gitlabhq/commit/c5feabde2d8cd023215af4d2ceeb7a64839fc428", - "author": { - "name": "Dmitriy Zaporozhets", - "email": "dmitriy.zaporozhets@gmail.com" - } - } - ], - "total_commits_count": 1 - }, - "target_title": null - }, - { - "title": null, - "project_id": 15, - "action_name": "closed", - "target_id": 840, - "target_type": "Issue", - "author_id": 1, - "data": null, - "target_title": "Finish & merge Code search PR", - "author": { - "name": "Dmitriy Zaporozhets", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", - "web_url": "http://localhost:3000/root" - }, - "author_username": "root" - }, - { - "title": null, - "project_id": 15, - "action_name": "commented on", - "target_id": 1312, - "target_type": "Note", - "author_id": 1, - "data": null, - "target_title": null, - "created_at": "2015-12-04T10:33:58.089Z", - "note": { - "id": 1312, - "body": "What an awesome day!", - "attachment": null, - "author": { - "name": "Dmitriy Zaporozhets", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", - "web_url": "http://localhost:3000/root" - }, - "created_at": "2015-12-04T10:33:56.698Z", - "system": false, - "noteable_id": 377, - "noteable_type": "Issue" - }, - "author": { - "name": "Dmitriy Zaporozhets", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", - "web_url": "http://localhost:3000/root" - }, - "author_username": "root" - } -] -``` +Please refer to the [Events API documentation](events.md#list-a-projects-visible-events) ### Create project diff --git a/doc/api/users.md b/doc/api/users.md index 7e118dcf4a9..f4167ba2605 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -701,147 +701,8 @@ Will return `201 OK` on success, `404 User Not Found` is user cannot be found or ### Get user contribution events -Get the contribution events for the specified user, sorted from newest to oldest. +Please refer to the [Events API documentation](events.md#get-user-contribution-events) -``` -GET /users/:id/events -``` - -Parameters: - -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the user | - -```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/:id/events -``` - -Example response: - -```json -[ - { - "title": null, - "project_id": 15, - "action_name": "closed", - "target_id": 830, - "target_type": "Issue", - "author_id": 1, - "data": null, - "target_title": "Public project search field", - "author": { - "name": "Dmitriy Zaporozhets", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", - "web_url": "http://localhost:3000/root" - }, - "author_username": "root" - }, - { - "title": null, - "project_id": 15, - "action_name": "opened", - "target_id": null, - "target_type": null, - "author_id": 1, - "author": { - "name": "Dmitriy Zaporozhets", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", - "web_url": "http://localhost:3000/root" - }, - "author_username": "john", - "data": { - "before": "50d4420237a9de7be1304607147aec22e4a14af7", - "after": "c5feabde2d8cd023215af4d2ceeb7a64839fc428", - "ref": "refs/heads/master", - "user_id": 1, - "user_name": "Dmitriy Zaporozhets", - "repository": { - "name": "gitlabhq", - "url": "git@dev.gitlab.org:gitlab/gitlabhq.git", - "description": "GitLab: self hosted Git management software. \r\nDistributed under the MIT License.", - "homepage": "https://dev.gitlab.org/gitlab/gitlabhq" - }, - "commits": [ - { - "id": "c5feabde2d8cd023215af4d2ceeb7a64839fc428", - "message": "Add simple search to projects in public area", - "timestamp": "2013-05-13T18:18:08+00:00", - "url": "https://dev.gitlab.org/gitlab/gitlabhq/commit/c5feabde2d8cd023215af4d2ceeb7a64839fc428", - "author": { - "name": "Dmitriy Zaporozhets", - "email": "dmitriy.zaporozhets@gmail.com" - } - } - ], - "total_commits_count": 1 - }, - "target_title": null - }, - { - "title": null, - "project_id": 15, - "action_name": "closed", - "target_id": 840, - "target_type": "Issue", - "author_id": 1, - "data": null, - "target_title": "Finish & merge Code search PR", - "author": { - "name": "Dmitriy Zaporozhets", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", - "web_url": "http://localhost:3000/root" - }, - "author_username": "root" - }, - { - "title": null, - "project_id": 15, - "action_name": "commented on", - "target_id": 1312, - "target_type": "Note", - "author_id": 1, - "data": null, - "target_title": null, - "created_at": "2015-12-04T10:33:58.089Z", - "note": { - "id": 1312, - "body": "What an awesome day!", - "attachment": null, - "author": { - "name": "Dmitriy Zaporozhets", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", - "web_url": "http://localhost:3000/root" - }, - "created_at": "2015-12-04T10:33:56.698Z", - "system": false, - "noteable_id": 377, - "noteable_type": "Issue" - }, - "author": { - "name": "Dmitriy Zaporozhets", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", - "web_url": "http://localhost:3000/root" - }, - "author_username": "root" - } -] -``` ## Get all impersonation tokens of a user |