diff options
Diffstat (limited to 'doc/api/group_labels.md')
-rw-r--r-- | doc/api/group_labels.md | 51 |
1 files changed, 45 insertions, 6 deletions
diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index 5030bba3159..f3c3a821354 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -16,6 +16,7 @@ GET /groups/:id/labels | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | | `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced in GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/31543))_ | +| `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels?with_counts=true @@ -50,6 +51,40 @@ Example response: ] ``` +## Get a single group label + +Get a single label for a given group. + +``` +GET /groups/:id/labels/:label_id +``` + +| 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. | +| `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels/bug +``` + +Example response: + +```json +{ + "id": 7, + "name": "bug", + "color": "#FF0000", + "text_color" : "#FFFFFF", + "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. @@ -90,19 +125,19 @@ Example response: Updates an existing group label. At least one parameter is required, to update the group label. ``` -PUT /groups/:id/labels +PUT /groups/:id/labels/:label_id ``` | 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 | +| `label_id` | integer or string | yes | The ID or title of a group's 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 +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"new_name": "Feature Idea" }' https://gitlab.example.com/api/v4/groups/5/labels/Feature%20Proposal ``` Example response: @@ -121,23 +156,27 @@ Example response: } ``` +NOTE: **Note:** An older endpoint `PUT /groups/:id/labels` with `name` in the params is still available, but deprecated. + ## Delete a group label Deletes a group label with a given name. ``` -DELETE /groups/:id/labels +DELETE /groups/:id/labels/:label_id ``` | 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. | +| `label_id` | integer or string | yes | The ID or title of a group's label. | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels?name=bug +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels/bug ``` +NOTE: **Note:** An older endpoint `DELETE /groups/:id/labels` with `name` in the params is still available, but deprecated. + ## Subscribe to a group label Subscribes the authenticated user to a group label to receive notifications. If |