Commit 29850364 authored by Rémy Coutable's avatar Rémy Coutable

New AccessRequests API endpoints for Group & Project

Also, mutualize AccessRequests and Members endpoints for Group &
Project.
New API documentation for the AccessRequests endpoints.
Signed-off-by: default avatarRémy Coutable <remy@rymai.me>
parent b1aac038
...@@ -7,6 +7,7 @@ v 8.11.0 (unreleased) ...@@ -7,6 +7,7 @@ v 8.11.0 (unreleased)
- Improve diff performance by eliminating redundant checks for text blobs - Improve diff performance by eliminating redundant checks for text blobs
- Convert switch icon into icon font (ClemMakesApps) - Convert switch icon into icon font (ClemMakesApps)
- API: Endpoints for enabling and disabling deploy keys - API: Endpoints for enabling and disabling deploy keys
- API: List access requests, request access, approve, and deny access requests to a project or a group. !4833
- Use long options for curl examples in documentation !5703 (winniehell) - Use long options for curl examples in documentation !5703 (winniehell)
- Remove magic comments (`# encoding: UTF-8`) from Ruby files. !5456 (winniehell) - Remove magic comments (`# encoding: UTF-8`) from Ruby files. !5456 (winniehell)
- Add support for relative links starting with ./ or / to RelativeLinkFilter (winniehell) - Add support for relative links starting with ./ or / to RelativeLinkFilter (winniehell)
......
...@@ -8,6 +8,7 @@ class ProjectMember < Member ...@@ -8,6 +8,7 @@ class ProjectMember < Member
# Make sure project member points only to project as it source # Make sure project member points only to project as it source
default_value_for :source_type, SOURCE_TYPE default_value_for :source_type, SOURCE_TYPE
validates_format_of :source_type, with: /\AProject\z/ validates_format_of :source_type, with: /\AProject\z/
validates :access_level, inclusion: { in: Gitlab::Access.values }
default_scope { where(source_type: SOURCE_TYPE) } default_scope { where(source_type: SOURCE_TYPE) }
scope :in_project, ->(project) { where(source_id: project.id) } scope :in_project, ->(project) { where(source_id: project.id) }
......
...@@ -999,6 +999,10 @@ class Project < ActiveRecord::Base ...@@ -999,6 +999,10 @@ class Project < ActiveRecord::Base
project_members.find_by(user_id: user) project_members.find_by(user_id: user)
end end
def add_user(user, access_level, current_user = nil)
team.add_user(user, access_level, current_user)
end
def default_branch def default_branch
@default_branch ||= repository.root_ref if repository.exists? @default_branch ||= repository.root_ref if repository.exists?
end end
......
...@@ -2,8 +2,9 @@ module Members ...@@ -2,8 +2,9 @@ module Members
class DestroyService < BaseService class DestroyService < BaseService
attr_accessor :member, :current_user attr_accessor :member, :current_user
def initialize(member, user) def initialize(member, current_user)
@member, @current_user = member, user @member = member
@current_user = current_user
end end
def execute def execute
......
...@@ -16,6 +16,8 @@ following locations: ...@@ -16,6 +16,8 @@ following locations:
- [Commits](commits.md) - [Commits](commits.md)
- [Deploy Keys](deploy_keys.md) - [Deploy Keys](deploy_keys.md)
- [Groups](groups.md) - [Groups](groups.md)
- [Group Access Requests](access_requests.md)
- [Group Members](members.md)
- [Issues](issues.md) - [Issues](issues.md)
- [Keys](keys.md) - [Keys](keys.md)
- [Labels](labels.md) - [Labels](labels.md)
...@@ -25,6 +27,8 @@ following locations: ...@@ -25,6 +27,8 @@ following locations:
- [Namespaces](namespaces.md) - [Namespaces](namespaces.md)
- [Notes](notes.md) (comments) - [Notes](notes.md) (comments)
- [Projects](projects.md) including setting Webhooks - [Projects](projects.md) including setting Webhooks
- [Project Access Requests](access_requests.md)
- [Project Members](members.md)
- [Project Snippets](project_snippets.md) - [Project Snippets](project_snippets.md)
- [Repositories](repositories.md) - [Repositories](repositories.md)
- [Repository Files](repository_files.md) - [Repository Files](repository_files.md)
...@@ -154,7 +158,7 @@ be returned with status code `403`: ...@@ -154,7 +158,7 @@ be returned with status code `403`:
```json ```json
{ {
"message": "403 Forbidden: Must be admin to use sudo" "message": "403 Forbidden - Must be admin to use sudo"
} }
``` ```
......
# Group and project access requests
>**Note:** This feature was introduced in GitLab 8.11
**Valid access levels**
The access levels are defined in the `Gitlab::Access` module. Currently, these levels are recognized:
```
10 => Guest access
20 => Reporter access
30 => Developer access
40 => Master access
50 => Owner access # Only valid for groups
```
## List access requests for a group or project
Gets a list of access requests viewable by the authenticated user.
Returns `200` if the request succeeds.
```
GET /groups/:id/access_requests
GET /projects/:id/access_requests
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |
```bash
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/:id/access_requests
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/:id/access_requests
```
Example response:
```json
[
{
"id": 1,
"username": "raymond_smith",
"name": "Raymond Smith",
"state": "active",
"created_at": "2012-10-22T14:13:35Z",
"requested_at": "2012-10-22T14:13:35Z"
},
{
"id": 2,
"username": "john_doe",
"name": "John Doe",
"state": "active",
"created_at": "2012-10-22T14:13:35Z",
"requested_at": "2012-10-22T14:13:35Z"
}
]
```
## Request access to a group or project
Requests access for the authenticated user to a group or project.
Returns `201` if the request succeeds.
```
POST /groups/:id/access_requests
POST /projects/:id/access_requests
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |
```bash
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/:id/access_requests
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/:id/access_requests
```
Example response:
```json
{
"id": 1,
"username": "raymond_smith",
"name": "Raymond Smith",
"state": "active",
"created_at": "2012-10-22T14:13:35Z",
"requested_at": "2012-10-22T14:13:35Z"
}
```
## Approve an access request
Approves an access request for the given user.
Returns `201` if the request succeeds.
```
PUT /groups/:id/access_requests/:user_id/approve
PUT /projects/:id/access_requests/:user_id/approve
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |
| `user_id` | integer | yes | The user ID of the access requester |
| `access_level` | integer | no | A valid access level (defaults: `30`, developer access level) |
```bash
curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/:id/access_requests/:user_id/approve?access_level=20
curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/:id/access_requests/:user_id/approve?access_level=20
```
Example response:
```json
{
"id": 1,
"username": "raymond_smith",
"name": "Raymond Smith",
"state": "active",
"created_at": "2012-10-22T14:13:35Z",
"access_level": 20
}
```
## Deny an access request
Denies an access request for the given user.
Returns `200` if the request succeeds.
```
DELETE /groups/:id/access_requests/:user_id
DELETE /projects/:id/access_requests/:user_id
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |
| `user_id` | integer | yes | The user ID of the access requester |
```bash
curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/:id/access_requests/:user_id
curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/:id/access_requests/:user_id
```
...@@ -417,87 +417,7 @@ GET /groups?search=foobar ...@@ -417,87 +417,7 @@ GET /groups?search=foobar
## Group members ## Group members
**Group access levels** Please consult the [Group Members](members.md) documentation.
The group access levels are defined in the `Gitlab::Access` module. Currently, these levels are recognized:
```
GUEST = 10
REPORTER = 20
DEVELOPER = 30
MASTER = 40
OWNER = 50
```
### List group members
Get a list of group members viewable by the authenticated user.
```
GET /groups/:id/members
```
```json
[
{
"id": 1,
"username": "raymond_smith",
"name": "Raymond Smith",
"state": "active",
"created_at": "2012-10-22T14:13:35Z",
"access_level": 30
},
{
"id": 2,
"username": "john_doe",
"name": "John Doe",
"state": "active",
"created_at": "2012-10-22T14:13:35Z",
"access_level": 30
}
]
```
### Add group member
Adds a user to the list of group members.
```
POST /groups/:id/members
```
Parameters:
- `id` (required) - The ID or path of a group
- `user_id` (required) - The ID of a user to add
- `access_level` (required) - Project access level
### Edit group team member
Updates a group team member to a specified access level.
```
PUT /groups/:id/members/:user_id
```
Parameters:
- `id` (required) - The ID of a group
- `user_id` (required) - The ID of a group member
- `access_level` (required) - Project access level
### Remove user team member
Removes user from user team.
```
DELETE /groups/:id/members/:user_id
```
Parameters:
- `id` (required) - The ID or path of a user group
- `user_id` (required) - The ID of a group member
## Namespaces in groups ## Namespaces in groups
......
# Group and project members
**Valid access levels**
The access levels are defined in the `Gitlab::Access` module. Currently, these levels are recognized:
```
10 => Guest access
20 => Reporter access
30 => Developer access
40 => Master access
50 => Owner access # Only valid for groups
```
## List all members of a group or project
Gets a list of group or project members viewable by the authenticated user.
Returns `200` if the request succeeds.
```
GET /groups/:id/members
GET /projects/:id/members
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |
| `query` | string | no | A query string to search for members |
```bash
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/:id/members
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/:id/members
```
Example response:
```json
[
{
"id": 1,
"username": "raymond_smith",
"name": "Raymond Smith",
"state": "active",
"created_at": "2012-10-22T14:13:35Z",
"access_level": 30
},
{
"id": 2,
"username": "john_doe",
"name": "John Doe",
"state": "active",
"created_at": "2012-10-22T14:13:35Z",
"access_level": 30
}
]
```
## Get a member of a group or project
Gets a member of a group or project.
Returns `200` if the request succeeds.
```
GET /groups/:id/members/:user_id
GET /projects/:id/members/:user_id
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |
| `user_id` | integer | yes | The user ID of the member |
```bash
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/:id/members/:user_id
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/:id/members/:user_id
```
Example response:
```json
{
"id": 1,
"username": "raymond_smith",
"name": "Raymond Smith",
"state": "active",
"created_at": "2012-10-22T14:13:35Z",
"access_level": 30
}
```
## Add a member to a group or project
Adds a member to a group or project.
Returns `201` if the request succeeds.
```
POST /groups/:id/members
POST /projects/:id/members
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |
| `user_id` | integer | yes | The user ID of the new member |
| `access_level` | integer | yes | A valid access level |
```bash
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/:id/members/:user_id?access_level=30
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/:id/members/:user_id?access_level=30
```
Example response:
```json
{
"id": 1,
"username": "raymond_smith",
"name": "Raymond Smith",
"state": "active",
"created_at": "2012-10-22T14:13:35Z",
"access_level": 30
}
```
## Edit a member of a group or project
Updates a member of a group or project.
Returns `200` if the request succeeds.
```
PUT /groups/:id/members/:user_id
PUT /projects/:id/members/:user_id
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |
| `user_id` | integer | yes | The user ID of the member |
| `access_level` | integer | yes | A valid access level |
```bash
curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/:id/members/:user_id?access_level=40
curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/:id/members/:user_id?access_level=40
```
Example response:
```json
{
"id": 1,
"username": "raymond_smith",
"name": "Raymond Smith",
"state": "active",
"created_at": "2012-10-22T14:13:35Z",
"access_level": 40
}
```
## Remove a member from a group or project
Removes a user from a group or project.
Returns `200` if the request succeeds.
```
DELETE /groups/:id/members/:user_id
DELETE /projects/:id/members/:user_id
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |
| `user_id` | integer | yes | The user ID of the member |
```bash
curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/:id/members/:user_id
curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/:id/members/:user_id
```
...@@ -858,95 +858,9 @@ Parameters: ...@@ -858,95 +858,9 @@ Parameters:
In Markdown contexts, the link is automatically expanded when the format in `markdown` is used. In Markdown contexts, the link is automatically expanded when the format in `markdown` is used.
## Team members ## Project members
### List project team members Please consult the [Project Members](members.md) documentation.
Get a list of a project's team members.
```
GET /projects/:id/members
```
Parameters:
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `query` (optional) - Query string to search for members
### Get project team member
Gets a project team member.
```
GET /projects/:id/members/:user_id
```
Parameters:
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `user_id` (required) - The ID of a user
```json
{
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"state": "active",
"created_at": "2012-05-23T08:00:58Z",
"access_level": 40
}
```
### Add project team member
Adds a user to a project team. This is an idempotent method and can be called multiple times
with the same parameters. Adding team membership to a user that is already a member does not
affect the existing membership.
```
POST /projects/:id/members
```
Parameters:
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `user_id` (required) - The ID of a user to add
- `access_level` (required) - Project access level
### Edit project team member
Updates a project team member to a specified access level.
```
PUT /projects/:id/members/:user_id
```
Parameters:
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `user_id` (required) - The ID of a team member
- `access_level` (required) - Project access level
### Remove project team member
Removes a user from a project team.
```
DELETE /projects/:id/members/:user_id
```
Parameters:
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `user_id` (required) - The ID of a team member
This method removes the project member if the user has the proper access rights to do so.
It returns a status code 403 if the member does not have the proper rights to perform this action.
In all other cases this method is idempotent and revoking team membership for a user who is not
currently a team member is considered success.
Please note that the returned JSON currently differs slightly. Thus you should not
rely on the returned JSON structure.
### Share project with group ### Share project with group
......
module API
class AccessRequests < Grape::API
before { authenticate! }
helpers ::API::Helpers::MembersHelpers
%w[group project].each do |source_type|
resource source_type.pluralize do
# Get a list of group/project access requests viewable by the authenticated user.
#
# Parameters:
# id (required) - The group/project ID
#
# Example Request:
# GET /groups/:id/access_requests
# GET /projects/:id/access_requests
get ":id/access_requests" do
source = find_source(source_type, params[:id])
authorize_admin_source!(source_type, source)
access_requesters = source.requesters
users = Kaminari.paginate_array(access_requesters.map(&:user))
present paginate(users), with: Entities::AccessRequester, source: source
end
# Request access to the group/project
#
# Parameters:
# id (required) - The group/project ID
#
# Example Request:
# POST /groups/:id/access_requests
# POST /projects/:id/access_requests
post ":id/access_requests" do
source = find_source(source_type, params[:id])
access_requester = source.request_access(current_user)
if access_requester.persisted?
present access_requester.user, with: Entities::AccessRequester, access_requester: access_requester
else
render_validation_error!(access_requester)
end
end
# Approve a group/project access request
#
# Parameters:
# id (required) - The group/project ID
# user_id (required) - The user ID of the access requester
# access_level (optional) - Access level
#
# Example Request:
# PUT /groups/:id/access_requests/:user_id/approve
# PUT /projects/:id/access_requests/:user_id/approve
put ':id/access_requests/:user_id/approve' do
required_attributes! [:user_id]
source = find_source(source_type, params[:id])
authorize_admin_source!(source_type, source)
member = source.requesters.find_by!(user_id: params[:user_id])
if params[:access_level]
member.update(access_level: params[:access_level])
end
member.accept_request
status :created
present member.user, with: Entities::Member, member: member
end
# Deny a group/project access request
#
# Parameters:
# id (required) - The group/project ID
# user_id (required) - The user ID of the access requester
#
# Example Request:
# DELETE /groups/:id/access_requests/:user_id
# DELETE /projects/:id/access_requests/:user_id
delete ":id/access_requests/:user_id" do
required_attributes! [:user_id]
source = find_source(source_type, params[:id])
access_requester = source.requesters.find_by!(user_id: params[:user_id])
::Members::DestroyService.new(access_requester, current_user).execute
end
end
end
end
end
...@@ -3,6 +3,10 @@ module API ...@@ -3,6 +3,10 @@ module API
include APIGuard include APIGuard
version 'v3', using: :path version 'v3', using: :path
rescue_from Gitlab::Access::AccessDeniedError do
rack_response({ 'message' => '403 Forbidden' }.to_json, 403)
end
rescue_from ActiveRecord::RecordNotFound do rescue_from ActiveRecord::RecordNotFound do
rack_response({ 'message' => '404 Not found' }.to_json, 404) rack_response({ 'message' => '404 Not found' }.to_json, 404)
end end
...@@ -32,6 +36,7 @@ module API ...@@ -32,6 +36,7 @@ module API
# Ensure the namespace is right, otherwise we might load Grape::API::Helpers # Ensure the namespace is right, otherwise we might load Grape::API::Helpers
helpers ::API::Helpers helpers ::API::Helpers
mount ::API::AccessRequests
mount ::API::AwardEmoji mount ::API::AwardEmoji
mount ::API::Branches mount ::API::Branches
mount ::API::Builds mount ::API::Builds
...@@ -40,19 +45,18 @@ module API ...@@ -40,19 +45,18 @@ module API
mount ::API::DeployKeys