GitLab wurde aktualisiert. Dank regelmäßiger Updates bleibt das THM GitLab sicher und Sie profitieren von den neuesten Funktionen. Vielen Dank für Ihre Geduld.

Commit d91b9645 authored by Sean McGivern's avatar Sean McGivern
Browse files

Merge branch 'api-group-labels' into 'master'

API group labels

Closes #44901

See merge request gitlab-org/gitlab-ce!21368
parents 6e519607 7c6efc00
......@@ -8,6 +8,7 @@ def initialize(params = {})
# returns the updated label
def execute(label)
params[:name] = params.delete(:new_name) if params.key?(:new_name)
params[:color] = convert_color_name_to_hex if params[:color].present?
label.update(params)
......
---
title: 'API: Add support for group labels'
merge_request: 21368
author: Robert Schilling
type: added
......@@ -29,6 +29,7 @@ The following API resources are available:
- [Group access requests](access_requests.md)
- [Group badges](group_badges.md)
- [Group issue boards](group_boards.md)
- [Group labels](group_labels.md)
- [Group-level variables](group_level_variables.md)
- [Group members](members.md)
- [Group milestones](group_milestones.md)
......
# Group Label API
>**Note:** This feature was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21368) in GitLab 11.8.
This API supports managing of [group labels](../user/project/labels.md#project-labels-and-group-labels). It allows to list, create, update, and delete group labels. Furthermore, users can subscribe and unsubscribe to and from group labels.
## List group labels
Get all labels for a given group.
```
GET /groups/:id/labels
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
```bash
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels
```
Example response:
```json
[
{
"id": 7,
"name": "bug",
"color": "#FF0000",
"description": null,
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": false
},
{
"id": 4,
"name": "feature",
"color": "#228B22",
"description": null,
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": false
}
]
```
## Create a new group label
Create a new group label for a given group.
```
POST /groups/:id/labels
```
| Attribute | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `name` | string | yes | The name of the label |
| `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) |
| `description` | string | no | The description of the label |
```bash
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"name": "Feature Proposal", "color": "#FFA500", "description": "Describes new ideas" }' https://gitlab.example.com/api/v4/groups/5/labels
```
Example response:
```json
{
"id": 9,
"name": "Feature Proposal",
"color": "#FFA500",
"description": "Describes new ideas",
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": false
}
```
## Update a group label
Updates an existing group label. At least one parameter is required, to update the group label.
```
PUT /groups/:id/labels
```
| Attribute | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `name` | string | yes | The name of the label |
| `new_name` | string | no | The new name of the label |
| `color` | string | no | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) |
| `description` | string | no | The description of the label |
```bash
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"name": "Feature Proposal", "new_name": "Feature Idea" }' https://gitlab.example.com/api/v4/groups/5/labels
```
Example response:
```json
{
"id": 9,
"name": "Feature Idea",
"color": "#FFA500",
"description": "Describes new ideas",
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": false
}
```
## Delete a group label
Deletes a group label with a given name.
```
DELETE /groups/:id/labels
```
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `name` | string | yes | The name of the label |
```bash
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels?name=bug
```
## Subscribe to a group label
Subscribes the authenticated user to a group label to receive notifications. If
the user is already subscribed to the label, the status code `304` is returned.
```
POST /groups/:id/labels/:label_id/subscribe
```
| Attribute | Type | Required | Description |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `label_id` | integer or string | yes | The ID or title of a group's label |
```bash
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels/9/subscribe
```
Example response:
```json
{
"id": 9,
"name": "Feature Idea",
"color": "#FFA500",
"description": "Describes new ideas",
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": true
}
```
## Unsubscribe from a group label
Unsubscribes the authenticated user from a group label to not receive
notifications from it. If the user is not subscribed to the label, the status
code `304` is returned.
```
POST /groups/:id/labels/:label_id/unsubscribe
```
| Attribute | Type | Required | Description |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `label_id` | integer or string | yes | The ID or title of a group's label |
```bash
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels/9/unsubscribe
```
Example response:
```json
{
"id": 9,
"name": "Feature Idea",
"color": "#FFA500",
"description": "Describes new ideas",
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": false
}
```
......@@ -109,6 +109,7 @@ class API < Grape::API
mount ::API::Features
mount ::API::Files
mount ::API::GroupBoards
mount ::API::GroupLabels
mount ::API::GroupMilestones
mount ::API::Groups
mount ::API::GroupVariables
......
......@@ -1019,12 +1019,17 @@ class Label < LabelBasic
label.open_merge_requests_count(options[:current_user])
end
expose :priority do |label, options|
label.priority(options[:project])
expose :subscribed do |label, options|
label.subscribed?(options[:current_user], options[:parent])
end
end
expose :subscribed do |label, options|
label.subscribed?(options[:current_user], options[:project])
class GroupLabel < Label
end
class ProjectLabel < Label
expose :priority do |label, options|
label.priority(options[:parent])
end
end
......
# frozen_string_literal: true
module API
class GroupLabels < Grape::API
include PaginationParams
helpers ::API::Helpers::LabelHelpers
before { authenticate! }
params do
requires :id, type: String, desc: 'The ID of a group'
end
resource :groups, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
desc 'Get all labels of the group' do
detail 'This feature was added in GitLab 11.8'
success Entities::GroupLabel
end
params do
use :pagination
end
get ':id/labels' do
get_labels(user_group, Entities::GroupLabel)
end
desc 'Create a new label' do
detail 'This feature was added in GitLab 11.8'
success Entities::GroupLabel
end
params do
use :label_create_params
end
post ':id/labels' do
create_label(user_group, Entities::GroupLabel)
end
desc 'Update an existing label. At least one optional parameter is required.' do
detail 'This feature was added in GitLab 11.8'
success Entities::GroupLabel
end
params do
requires :name, type: String, desc: 'The name of the label to be updated'
optional :new_name, type: String, desc: 'The new name of the label'
optional :color, type: String, desc: "The new color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the allowed CSS color names"
optional :description, type: String, desc: 'The new description of label'
at_least_one_of :new_name, :color, :description
end
put ':id/labels' do
update_label(user_group, Entities::GroupLabel)
end
desc 'Delete an existing label' do
detail 'This feature was added in GitLab 11.8'
success Entities::GroupLabel
end
params do
requires :name, type: String, desc: 'The name of the label to be deleted'
end
delete ':id/labels' do
delete_label(user_group)
end
end
end
end
......@@ -84,8 +84,8 @@ def wiki_page
page || not_found!('Wiki Page')
end
def available_labels_for(label_parent)
search_params = { include_ancestor_groups: true }
def available_labels_for(label_parent, include_ancestor_groups: true)
search_params = { include_ancestor_groups: include_ancestor_groups }
if label_parent.is_a?(Project)
search_params[:project_id] = label_parent.id
......@@ -170,13 +170,6 @@ def find_branch!(branch_name)
end
end
def find_project_label(id)
labels = available_labels_for(user_project)
label = labels.find_by_id(id) || labels.find_by_title(id)
label || not_found!('Label')
end
# rubocop: disable CodeReuse/ActiveRecord
def find_project_issue(iid)
IssuesFinder.new(current_user, project_id: user_project.id).find_by!(iid: iid)
......
# frozen_string_literal: true
module API
module Helpers
module LabelHelpers
extend Grape::API::Helpers
params :label_create_params do
requires :name, type: String, desc: 'The name of the label to be created'
requires :color, type: String, desc: "The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the allowed CSS color names"
optional :description, type: String, desc: 'The description of label to be created'
end
def find_label(parent, id, include_ancestor_groups: true)
labels = available_labels_for(parent, include_ancestor_groups: include_ancestor_groups)
label = labels.find_by_id(id) || labels.find_by_title(id)
label || not_found!('Label')
end
def get_labels(parent, entity)
present paginate(available_labels_for(parent)), with: entity, current_user: current_user, parent: parent
end
def create_label(parent, entity)
authorize! :admin_label, parent
label = available_labels_for(parent).find_by_title(params[:name])
conflict!('Label already exists') if label
priority = params.delete(:priority)
label_params = declared_params(include_missing: false)
label =
if parent.is_a?(Project)
::Labels::CreateService.new(label_params).execute(project: parent)
else
::Labels::CreateService.new(label_params).execute(group: parent)
end
if label.persisted?
if parent.is_a?(Project)
label.prioritize!(parent, priority) if priority
end
present label, with: entity, current_user: current_user, parent: parent
else
render_validation_error!(label)
end
end
def update_label(parent, entity)
authorize! :admin_label, parent
label = find_label(parent, params[:name], include_ancestor_groups: false)
update_priority = params.key?(:priority)
priority = params.delete(:priority)
label = ::Labels::UpdateService.new(declared_params(include_missing: false)).execute(label)
render_validation_error!(label) unless label.valid?
if parent.is_a?(Project) && update_priority
if priority.nil?
label.unprioritize!(parent)
else
label.prioritize!(parent, priority)
end
end
present label, with: entity, current_user: current_user, parent: parent
end
def delete_label(parent)
authorize! :admin_label, parent
label = find_label(parent, params[:name], include_ancestor_groups: false)
destroy_conditionally!(label)
end
end
end
end
......@@ -3,6 +3,7 @@
module API
class Labels < Grape::API
include PaginationParams
helpers ::API::Helpers::LabelHelpers
before { authenticate! }
......@@ -11,62 +12,28 @@ class Labels < Grape::API
end
resource :projects, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
desc 'Get all labels of the project' do
success Entities::Label
success Entities::ProjectLabel
end
params do
use :pagination
end
get ':id/labels' do
present paginate(available_labels_for(user_project)), with: Entities::Label, current_user: current_user, project: user_project
get_labels(user_project, Entities::ProjectLabel)
end
desc 'Create a new label' do
success Entities::Label
success Entities::ProjectLabel
end
params do
requires :name, type: String, desc: 'The name of the label to be created'
requires :color, type: String, desc: "The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the allowed CSS color names"
optional :description, type: String, desc: 'The description of label to be created'
use :label_create_params
optional :priority, type: Integer, desc: 'The priority of the label', allow_blank: true
end
# rubocop: disable CodeReuse/ActiveRecord
post ':id/labels' do
authorize! :admin_label, user_project
label = available_labels_for(user_project).find_by(title: params[:name])
conflict!('Label already exists') if label
priority = params.delete(:priority)
label = ::Labels::CreateService.new(declared_params(include_missing: false)).execute(project: user_project)
if label.valid?
label.prioritize!(user_project, priority) if priority
present label, with: Entities::Label, current_user: current_user, project: user_project
else
render_validation_error!(label)
end
end
# rubocop: enable CodeReuse/ActiveRecord
desc 'Delete an existing label' do
success Entities::Label
end
params do
requires :name, type: String, desc: 'The name of the label to be deleted'
end
# rubocop: disable CodeReuse/ActiveRecord
delete ':id/labels' do
authorize! :admin_label, user_project
label = user_project.labels.find_by(title: params[:name])
not_found!('Label') unless label
destroy_conditionally!(label)
create_label(user_project, Entities::ProjectLabel)
end
# rubocop: enable CodeReuse/ActiveRecord
desc 'Update an existing label. At least one optional parameter is required.' do
success Entities::Label
success Entities::ProjectLabel
end
params do
requires :name, type: String, desc: 'The name of the label to be updated'
......@@ -76,33 +43,19 @@ class Labels < Grape::API
optional :priority, type: Integer, desc: 'The priority of the label', allow_blank: true
at_least_one_of :new_name, :color, :description, :priority
end
# rubocop: disable CodeReuse/ActiveRecord
put ':id/labels' do
authorize! :admin_label, user_project
label = user_project.labels.find_by(title: params[:name])
not_found!('Label not found') unless label
update_priority = params.key?(:priority)
priority = params.delete(:priority)
label_params = declared_params(include_missing: false)
# Rename new name to the actual label attribute name
label_params[:name] = label_params.delete(:new_name) if label_params.key?(:new_name)
label = ::Labels::UpdateService.new(label_params).execute(label)
render_validation_error!(label) unless label.valid?
if update_priority
if priority.nil?
label.unprioritize!(user_project)
else
label.prioritize!(user_project, priority)
end
end
update_label(user_project, Entities::ProjectLabel)
end
present label, with: Entities::Label, current_user: current_user, project: user_project
desc 'Delete an existing label' do
success Entities::ProjectLabel
end
params do
requires :name, type: String, desc: 'The name of the label to be deleted'
end
delete ':id/labels' do
delete_label(user_project)
end
# rubocop: enable CodeReuse/ActiveRecord
end
end
end
......@@ -2,51 +2,88 @@
module API
class Subscriptions < Grape::API
helpers ::API::Helpers::LabelHelpers
before { authenticate! }
subscribable_types = {
'merge_requests' => proc { |id| find_merge_request_with_access(id, :update_merge_request) },
'issues' => proc { |id| find_project_issue(id) },
'labels' => proc { |id| find_project_label(id) }
}
subscribables = [
{
type: 'merge_requests',
entity: Entities::MergeRequest,
source: Project,
finder: ->(id) { find_merge_request_with_access(id, :update_merge_request) }
},
{
type: 'issues',
entity: Entities::Issue,
source: Project,
finder: ->(id) { find_project_issue(id) }
},
{
type: 'labels',
entity: Entities::ProjectLabel,
source: Project,
finder: ->(id) { find_label(user_project, id) }
},
{
type: 'labels',
entity: Entities::GroupLabel,
source: Group,
finder: ->(id) { find_label(user_group, id) }
}
]
params do
requires :id, type: String, desc: 'The ID of a project'
requires :subscribable_id, type: String, desc: 'The ID of a resource'
end
resource :projects, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
subscribable_types.each do |type, finder|
type_singularized = type.singularize
entity_class = Entities.const_get(type_singularized.camelcase)
subscribables.each do |subscribable|
source_type = subscribable[:source].name.underscore
params do
requires :id, type: String, desc: "The #{source_type} ID"
requires :subscribable_id, type: String, desc: 'The ID of a resource'
end
resource source_type.pluralize, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
desc 'Subscribe to a resource' do
success entity_class
success subscribable[:entity]
end
post ":id/#{type}/:subscribable_id/subscribe" do
resource = instance_exec(params[:subscribable_id], &finder)
post ":id/#{subscribable[:type]}/:subscribable_id/subscribe" do
parent = parent_resource(source_type)
resource = instance_exec(params[:subscribable_id], &subscribable[:finder])
if resource.subscribed?(current_user, user_project)
if resource.subscribed?(current_user, parent)
not_modified!
else
resource.subscribe(current_user,