diff --git a/CHANGELOG b/CHANGELOG index 8049894917e..d4268fc3709 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -5,6 +5,7 @@ v 8.13.0 (unreleased) - Add link from system note to compare with previous version - Improve issue load time performance by avoiding ORDER BY in find_by call - Use gitlab-shell v3.6.2 (GIT TRACE logging) + - Add `/projects/visible` API endpoint (Ben Boeckel) - Fix centering of custom header logos (Ashley Dumaine) - AbstractReferenceFilter caches project_refs on RequestStore when active - Replaced the check sign to arrow in the show build view. !6501 diff --git a/doc/api/projects.md b/doc/api/projects.md index 869907b0dd7..27436a052da 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -20,7 +20,7 @@ Constants for project visibility levels are next: ## List projects -Get a list of projects accessible by the authenticated user. +Get a list of projects for which the authenticated user is a member. ``` GET /projects @@ -28,11 +28,14 @@ GET /projects Parameters: -- `archived` (optional) - if passed, limit by archived status -- `visibility` (optional) - if passed, limit by visibility `public`, `internal`, `private` -- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at` -- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc` -- `search` (optional) - Return list of authorized projects according to a search criteria +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `archived` | boolean | no | Limit by archived status | +| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | +| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | +| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Return list of authorized projects matching the search criteria | +| `simple` | boolean | no | Return only the ID, URL, name, and path of each project | ```json [ @@ -153,6 +156,138 @@ Parameters: ] ``` +Get a list of projects which the authenticated user can see. + +``` +GET /projects/visible +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `archived` | boolean | no | Limit by archived status | +| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | +| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | +| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Return list of authorized projects matching the search criteria | +| `simple` | boolean | no | Return only the ID, URL, name, and path of each project | + +```json +[ + { + "id": 4, + "description": null, + "default_branch": "master", + "public": false, + "visibility_level": 0, + "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git", + "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git", + "web_url": "http://example.com/diaspora/diaspora-client", + "tag_list": [ + "example", + "disapora client" + ], + "owner": { + "id": 3, + "name": "Diaspora", + "created_at": "2013-09-30T13:46:02Z" + }, + "name": "Diaspora Client", + "name_with_namespace": "Diaspora / Diaspora Client", + "path": "diaspora-client", + "path_with_namespace": "diaspora/diaspora-client", + "issues_enabled": true, + "open_issues_count": 1, + "merge_requests_enabled": true, + "builds_enabled": true, + "wiki_enabled": true, + "snippets_enabled": false, + "container_registry_enabled": false, + "created_at": "2013-09-30T13:46:02Z", + "last_activity_at": "2013-09-30T13:46:02Z", + "creator_id": 3, + "namespace": { + "created_at": "2013-09-30T13:46:02Z", + "description": "", + "id": 3, + "name": "Diaspora", + "owner_id": 1, + "path": "diaspora", + "updated_at": "2013-09-30T13:46:02Z" + }, + "archived": false, + "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png", + "shared_runners_enabled": true, + "forks_count": 0, + "star_count": 0, + "runners_token": "b8547b1dc37721d05889db52fa2f02", + "public_builds": true, + "shared_with_groups": [] + }, + { + "id": 6, + "description": null, + "default_branch": "master", + "public": false, + "visibility_level": 0, + "ssh_url_to_repo": "git@example.com:brightbox/puppet.git", + "http_url_to_repo": "http://example.com/brightbox/puppet.git", + "web_url": "http://example.com/brightbox/puppet", + "tag_list": [ + "example", + "puppet" + ], + "owner": { + "id": 4, + "name": "Brightbox", + "created_at": "2013-09-30T13:46:02Z" + }, + "name": "Puppet", + "name_with_namespace": "Brightbox / Puppet", + "path": "puppet", + "path_with_namespace": "brightbox/puppet", + "issues_enabled": true, + "open_issues_count": 1, + "merge_requests_enabled": true, + "builds_enabled": true, + "wiki_enabled": true, + "snippets_enabled": false, + "container_registry_enabled": false, + "created_at": "2013-09-30T13:46:02Z", + "last_activity_at": "2013-09-30T13:46:02Z", + "creator_id": 3, + "namespace": { + "created_at": "2013-09-30T13:46:02Z", + "description": "", + "id": 4, + "name": "Brightbox", + "owner_id": 1, + "path": "brightbox", + "updated_at": "2013-09-30T13:46:02Z" + }, + "permissions": { + "project_access": { + "access_level": 10, + "notification_level": 3 + }, + "group_access": { + "access_level": 50, + "notification_level": 3 + } + }, + "archived": false, + "avatar_url": null, + "shared_runners_enabled": true, + "forks_count": 0, + "star_count": 0, + "runners_token": "b8547b1dc37721d05889db52fa2f02", + "public_builds": true, + "shared_with_groups": [] + } +] +``` + ### List owned projects Get a list of projects which are owned by the authenticated user. @@ -163,11 +298,13 @@ GET /projects/owned Parameters: -- `archived` (optional) - if passed, limit by archived status -- `visibility` (optional) - if passed, limit by visibility `public`, `internal`, `private` -- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at` -- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc` -- `search` (optional) - Return list of authorized projects according to a search criteria +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `archived` | boolean | no | Limit by archived status | +| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | +| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | +| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Return list of authorized projects matching the search criteria | ### List starred projects @@ -179,11 +316,13 @@ GET /projects/starred Parameters: -- `archived` (optional) - if passed, limit by archived status -- `visibility` (optional) - if passed, limit by visibility `public`, `internal`, `private` -- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at` -- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc` -- `search` (optional) - Return list of authorized projects according to a search criteria +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `archived` | boolean | no | Limit by archived status | +| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | +| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | +| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Return list of authorized projects matching the search criteria | ### List ALL projects @@ -195,11 +334,13 @@ GET /projects/all Parameters: -- `archived` (optional) - if passed, limit by archived status -- `visibility` (optional) - if passed, limit by visibility `public`, `internal`, `private` -- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at` -- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc` -- `search` (optional) - Return list of authorized projects according to a search criteria +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `archived` | boolean | no | Limit by archived status | +| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | +| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | +| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Return list of authorized projects matching the search criteria | ### Get single project @@ -212,7 +353,9 @@ GET /projects/:id Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or NAMESPACE/PROJECT_NAME of the project | ```json { @@ -301,7 +444,9 @@ GET /projects/:id/events Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or NAMESPACE/PROJECT_NAME of the project | ```json [ @@ -439,24 +584,26 @@ POST /projects Parameters: -- `name` (required) - new project name -- `path` (optional) - custom repository name for new project. By default generated based on name -- `namespace_id` (optional) - namespace for the new project (defaults to user) -- `description` (optional) - short project description -- `issues_enabled` (optional) -- `merge_requests_enabled` (optional) -- `builds_enabled` (optional) -- `wiki_enabled` (optional) -- `snippets_enabled` (optional) -- `container_registry_enabled` (optional) -- `shared_runners_enabled` (optional) -- `public` (optional) - if `true` same as setting visibility_level = 20 -- `visibility_level` (optional) -- `import_url` (optional) -- `public_builds` (optional) -- `only_allow_merge_if_build_succeeds` (optional) -- `lfs_enabled` (optional) -- `request_access_enabled` (optional) - Allow users to request member access. +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `name` | string | yes | The name of the new project | +| `path` | string | no | Custom repository name for new project. By default generated based on name | +| `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) | +| `description` | string | no | Short project description | +| `issues_enabled` | boolean | no | Enable issues for this project | +| `merge_requests_enabled` | boolean | no | Enable merge requests for this project | +| `builds_enabled` | boolean | no | Enable builds for this project | +| `wiki_enabled` | boolean | no | Enable wiki for this project | +| `snippets_enabled` | boolean | no | Enable snippets for this project | +| `container_registry_enabled` | boolean | no | Enable container registry for this project | +| `shared_runners_enabled` | boolean | no | Enable shared runners for this project | +| `public` | boolean | no | If `true`, the same as setting `visibility_level` to 20 | +| `visibility_level` | integer | no | See [project visibility level][#project-visibility-level] | +| `import_url` | string | no | URL to import repository from | +| `public_builds` | boolean | no | If `true`, builds can be viewed by non-project-members | +| `only_allow_merge_if_build_succeeds` | boolean | no | Set whether merge requests can only be merged with successful builds | +| `lfs_enabled` | boolean | no | Enable LFS | +| `request_access_enabled` | boolean | no | Allow users to request member access | ### Create project for user @@ -468,23 +615,27 @@ POST /projects/user/:user_id Parameters: -- `user_id` (required) - user_id of owner -- `name` (required) - new project name -- `description` (optional) - short project description -- `issues_enabled` (optional) -- `merge_requests_enabled` (optional) -- `builds_enabled` (optional) -- `wiki_enabled` (optional) -- `snippets_enabled` (optional) -- `container_registry_enabled` (optional) -- `shared_runners_enabled` (optional) -- `public` (optional) - if `true` same as setting visibility_level = 20 -- `visibility_level` (optional) -- `import_url` (optional) -- `public_builds` (optional) -- `only_allow_merge_if_build_succeeds` (optional) -- `lfs_enabled` (optional) -- `request_access_enabled` (optional) - Allow users to request member access. +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `user_id` | integer | yes | The user ID of the project owner | +| `name` | string | yes | The name of the new project | +| `path` | string | no | Custom repository name for new project. By default generated based on name | +| `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) | +| `description` | string | no | Short project description | +| `issues_enabled` | boolean | no | Enable issues for this project | +| `merge_requests_enabled` | boolean | no | Enable merge requests for this project | +| `builds_enabled` | boolean | no | Enable builds for this project | +| `wiki_enabled` | boolean | no | Enable wiki for this project | +| `snippets_enabled` | boolean | no | Enable snippets for this project | +| `container_registry_enabled` | boolean | no | Enable container registry for this project | +| `shared_runners_enabled` | boolean | no | Enable shared runners for this project | +| `public` | boolean | no | If `true`, the same as setting `visibility_level` to 20 | +| `visibility_level` | integer | no | See [project visibility level][#project-visibility-level] | +| `import_url` | string | no | URL to import repository from | +| `public_builds` | boolean | no | If `true`, builds can be viewed by non-project-members | +| `only_allow_merge_if_build_succeeds` | boolean | no | Set whether merge requests can only be merged with successful builds | +| `lfs_enabled` | boolean | no | Enable LFS | +| `request_access_enabled` | boolean | no | Allow users to request member access | ### Edit project @@ -496,24 +647,26 @@ PUT /projects/:id Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `name` (optional) - project name -- `path` (optional) - repository name for project -- `description` (optional) - short project description -- `default_branch` (optional) -- `issues_enabled` (optional) -- `merge_requests_enabled` (optional) -- `builds_enabled` (optional) -- `wiki_enabled` (optional) -- `snippets_enabled` (optional) -- `container_registry_enabled` (optional) -- `shared_runners_enabled` (optional) -- `public` (optional) - if `true` same as setting visibility_level = 20 -- `visibility_level` (optional) -- `public_builds` (optional) -- `only_allow_merge_if_build_succeeds` (optional) -- `lfs_enabled` (optional) -- `request_access_enabled` (optional) - Allow users to request member access. +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or NAMESPACE/PROJECT_NAME of the project | +| `name` | string | yes | The name of the project | +| `path` | string | no | Custom repository name for the project. By default generated based on name | +| `description` | string | no | Short project description | +| `issues_enabled` | boolean | no | Enable issues for this project | +| `merge_requests_enabled` | boolean | no | Enable merge requests for this project | +| `builds_enabled` | boolean | no | Enable builds for this project | +| `wiki_enabled` | boolean | no | Enable wiki for this project | +| `snippets_enabled` | boolean | no | Enable snippets for this project | +| `container_registry_enabled` | boolean | no | Enable container registry for this project | +| `shared_runners_enabled` | boolean | no | Enable shared runners for this project | +| `public` | boolean | no | If `true`, the same as setting `visibility_level` to 20 | +| `visibility_level` | integer | no | See [project visibility level][#project-visibility-level] | +| `import_url` | string | no | URL to import repository from | +| `public_builds` | boolean | no | If `true`, builds can be viewed by non-project-members | +| `only_allow_merge_if_build_succeeds` | boolean | no | Set whether merge requests can only be merged with successful builds | +| `lfs_enabled` | boolean | no | Enable LFS | +| `request_access_enabled` | boolean | no | Allow users to request member access | On success, method returns 200 with the updated project. If parameters are invalid, 400 is returned. @@ -528,8 +681,10 @@ POST /projects/fork/:id Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked -- `namespace` (optional) - The ID or path of the namespace that the project will be forked to +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or NAMESPACE/PROJECT_NAME of the project | +| `namespace` | integer/string | yes | The ID or path of the namespace that the project will be forked to | ### Star a project @@ -540,9 +695,11 @@ Stars a given project. Returns status code `201` and the project on success and POST /projects/:id/star ``` +Parameters: + | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or NAMESPACE/PROJECT_NAME of the project | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/star" @@ -610,7 +767,7 @@ DELETE /projects/:id/star | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/star" @@ -682,7 +839,7 @@ POST /projects/:id/archive | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/archive" @@ -770,7 +927,7 @@ POST /projects/:id/unarchive | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/unarchive" @@ -853,7 +1010,9 @@ DELETE /projects/:id Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ## Uploads @@ -867,8 +1026,10 @@ POST /projects/:id/uploads Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked -- `file` (required) - The file to be uploaded +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `file` | string | yes | The file to be uploaded | ```json { @@ -896,10 +1057,12 @@ POST /projects/:id/share Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked -- `group_id` (required) - The ID of a group -- `group_access` (required) - Level of permissions for sharing -- `expires_at` - Share expiration date in ISO 8601 format: 2016-09-26 +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `group_id` | integer | yes | The ID of the group to share with | +| `group_access` | integer | yes | The permissions level to grant the group | +| `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 | ## Hooks @@ -916,7 +1079,9 @@ GET /projects/:id/hooks Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ### Get project hook @@ -928,8 +1093,10 @@ GET /projects/:id/hooks/:hook_id Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `hook_id` (required) - The ID of a project hook +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `hook_id` | integer | yes | The ID of a project hook | ```json { @@ -959,17 +1126,19 @@ POST /projects/:id/hooks Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `url` (required) - The hook URL -- `push_events` - Trigger hook on push events -- `issues_events` - Trigger hook on issues events -- `merge_requests_events` - Trigger hook on merge_requests events -- `tag_push_events` - Trigger hook on push_tag events -- `note_events` - Trigger hook on note events -- `build_events` - Trigger hook on build events -- `pipeline_events` - Trigger hook on pipeline events -- `wiki_page_events` - Trigger hook on wiki page events -- `enable_ssl_verification` - Do SSL verification when triggering the hook +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `url` | string | yes | The hook URL | +| `push_events` | boolean | no | Trigger hook on push events | +| `issues_events` | boolean | no | Trigger hook on issues events | +| `merge_requests_events` | boolean | no | Trigger hook on merge requests events | +| `tag_push_events` | boolean | no | Trigger hook on tag push events | +| `note_events` | boolean | no | Trigger hook on note events | +| `build_events` | boolean | no | Trigger hook on build events | +| `pipeline_events` | boolean | no | Trigger hook on pipeline events | +| `wiki_events` | boolean | no | Trigger hook on wiki events | +| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | ### Edit project hook @@ -981,18 +1150,20 @@ PUT /projects/:id/hooks/:hook_id Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `hook_id` (required) - The ID of a project hook -- `url` (required) - The hook URL -- `push_events` - Trigger hook on push events -- `issues_events` - Trigger hook on issues events -- `merge_requests_events` - Trigger hook on merge_requests events -- `tag_push_events` - Trigger hook on push_tag events -- `note_events` - Trigger hook on note events -- `build_events` - Trigger hook on build events -- `pipeline_events` - Trigger hook on pipeline events -- `wiki_page_events` - Trigger hook on wiki page events -- `enable_ssl_verification` - Do SSL verification when triggering the hook +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `hook_id` | integer | yes | The ID of the project hook | +| `url` | string | yes | The hook URL | +| `push_events` | boolean | no | Trigger hook on push events | +| `issues_events` | boolean | no | Trigger hook on issues events | +| `merge_requests_events` | boolean | no | Trigger hook on merge requests events | +| `tag_push_events` | boolean | no | Trigger hook on tag push events | +| `note_events` | boolean | no | Trigger hook on note events | +| `build_events` | boolean | no | Trigger hook on build events | +| `pipeline_events` | boolean | no | Trigger hook on pipeline events | +| `wiki_events` | boolean | no | Trigger hook on wiki events | +| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | ### Delete project hook @@ -1005,8 +1176,10 @@ DELETE /projects/:id/hooks/:hook_id Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `hook_id` (required) - The ID of hook to delete +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `hook_id` | integer | yes | The ID of the project hook | Note the JSON response differs if the hook is available or not. If the project hook is available before it is returned in the JSON response or an empty response is returned. @@ -1025,7 +1198,9 @@ GET /projects/:id/repository/branches Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```json [ @@ -1080,10 +1255,12 @@ GET /projects/:id/repository/branches/:branch Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `branch` (required) - The name of the branch. -- `developers_can_push` - Flag if developers can push to the branch. -- `developers_can_merge` - Flag if developers can merge to the branch. +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `branch` | string | yes | The name of the branch | +| `developers_can_push` | boolean | no | Flag if developers can push to the branch | +| `developers_can_merge` | boolean | no | Flag if developers can merge to the branch | ### Protect single branch @@ -1095,8 +1272,10 @@ PUT /projects/:id/repository/branches/:branch/protect Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `branch` (required) - The name of the branch. +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `branch` | string | yes | The name of the branch | ### Unprotect single branch @@ -1108,8 +1287,10 @@ PUT /projects/:id/repository/branches/:branch/unprotect Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `branch` (required) - The name of the branch. +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `branch` | string | yes | The name of the branch | ## Admin fork relation @@ -1123,8 +1304,10 @@ POST /projects/:id/fork/:forked_from_id Parameters: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked -- `forked_from_id:` (required) - The ID of the project that was forked from +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `forked_from_id` | ID | yes | The ID of the project that was forked from | ### Delete an existing forked from relationship @@ -1134,7 +1317,9 @@ DELETE /projects/:id/fork Parameter: -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ## Search for projects by name @@ -1146,8 +1331,10 @@ GET /projects/search/:query Parameters: -- `query` (required) - A string contained in the project name -- `per_page` (optional) - number of projects to return per page -- `page` (optional) - the page to retrieve -- `order_by` (optional) - Return requests ordered by `id`, `name`, `created_at` or `last_activity_at` fields -- `sort` (optional) - Return requests sorted in `asc` or `desc` order +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `query` (required) - A string contained in the project name +| `per_page` (optional) - number of projects to return per page +| `page` (optional) - the page to retrieve +| `order_by` (optional) - Return requests ordered by `id`, `name`, `created_at` or `last_activity_at` fields +| `sort` | string | no | Return requests sorted in `asc` or `desc` order | diff --git a/lib/api/projects.rb b/lib/api/projects.rb index 680055c95eb..c24e8e8bd9b 100644 --- a/lib/api/projects.rb +++ b/lib/api/projects.rb @@ -22,14 +22,25 @@ module API # Example Request: # GET /projects get do - @projects = current_user.authorized_projects - @projects = filter_projects(@projects) - @projects = paginate @projects - if params[:simple] - present @projects, with: Entities::BasicProjectDetails, user: current_user - else - present @projects, with: Entities::ProjectWithAccess, user: current_user - end + projects = current_user.authorized_projects + projects = filter_projects(projects) + projects = paginate projects + entity = params[:simple] ? Entities::BasicProjectDetails : Entities::ProjectWithAccess + + present projects, with: entity, user: current_user + end + + # Get a list of visible projects for authenticated user + # + # Example Request: + # GET /projects/visible + get '/visible' do + projects = ProjectsFinder.new.execute(current_user) + projects = filter_projects(projects) + projects = paginate projects + entity = params[:simple] ? Entities::BasicProjectDetails : Entities::ProjectWithAccess + + present projects, with: entity, user: current_user end # Get an owned projects list for authenticated user @@ -37,10 +48,10 @@ module API # Example Request: # GET /projects/owned get '/owned' do - @projects = current_user.owned_projects - @projects = filter_projects(@projects) - @projects = paginate @projects - present @projects, with: Entities::ProjectWithAccess, user: current_user + projects = current_user.owned_projects + projects = filter_projects(projects) + projects = paginate projects + present projects, with: Entities::ProjectWithAccess, user: current_user end # Gets starred project for the authenticated user @@ -48,10 +59,10 @@ module API # Example Request: # GET /projects/starred get '/starred' do - @projects = current_user.viewable_starred_projects - @projects = filter_projects(@projects) - @projects = paginate @projects - present @projects, with: Entities::Project, user: current_user + projects = current_user.viewable_starred_projects + projects = filter_projects(projects) + projects = paginate projects + present projects, with: Entities::Project, user: current_user end # Get all projects for admin user @@ -60,10 +71,10 @@ module API # GET /projects/all get '/all' do authenticated_as_admin! - @projects = Project.all - @projects = filter_projects(@projects) - @projects = paginate @projects - present @projects, with: Entities::ProjectWithAccess, user: current_user + projects = Project.all + projects = filter_projects(projects) + projects = paginate projects + present projects, with: Entities::ProjectWithAccess, user: current_user end # Get a single project diff --git a/spec/requests/api/projects_spec.rb b/spec/requests/api/projects_spec.rb index 861eb12b94c..5f19638b460 100644 --- a/spec/requests/api/projects_spec.rb +++ b/spec/requests/api/projects_spec.rb @@ -175,6 +175,36 @@ describe API::API, api: true do end end + describe 'GET /projects/visible' do + let(:public_project) { create(:project, :public) } + + before do + public_project + project + project2 + project3 + project4 + end + + it 'returns the projects viewable by the user' do + get api('/projects/visible', user) + + expect(response).to have_http_status(200) + expect(json_response).to be_an Array + expect(json_response.map { |project| project['id'] }). + to contain_exactly(public_project.id, project.id, project2.id, project3.id) + end + + it 'shows only public projects when the user only has access to those' do + get api('/projects/visible', user2) + + expect(response).to have_http_status(200) + expect(json_response).to be_an Array + expect(json_response.map { |project| project['id'] }). + to contain_exactly(public_project.id) + end + end + describe 'GET /projects/starred' do let(:public_project) { create(:project, :public) }