Add latest changes from gitlab-org/gitlab@master

1 files changed, 51 insertions, 11 deletions

diff --git a/doc/api/labels.md b/doc/api/labels.md
index f29c0a28cdf..525dbe02e5f 100644
--- a/doc/api/labels.md
+++ b/doc/api/labels.md
@@ -90,6 +90,42 @@ Example response:
 ]
 ```
 
+## Get a single project label
+
+Get a single label for a given project.
+
+```
+GET /projects/:id/labels/:label_id
+```
+
+| Attribute     | Type           | Required | Description                                                                                                                                                                  |
+| ---------     | -------        | -------- | ---------------------                                                                                                                                                        |
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](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/projects/1/labels/bug
+```
+
+Example response:
+
+```json
+{
+  "id" : 1,
+  "name" : "bug",
+  "color" : "#d9534f",
+  "text_color" : "#FFFFFF",
+  "description": "Bug reported by user",
+  "open_issues_count": 1,
+  "closed_issues_count": 0,
+  "open_merge_requests_count": 1,
+  "subscribed": false,
+  "priority": 10,
+  "is_project_label": true
+}
+```
+
 ## Create a new label
 
 Creates a new label for the given repository with the given name and color.
@@ -133,40 +169,40 @@ Example response:
 Deletes a label with a given name.
 
 ```
-DELETE /projects/:id/labels
+DELETE /projects/:id/labels/:label_id
 ```
 
 | Attribute | Type    | Required | Description           |
 | --------- | ------- | -------- | --------------------- |
 | `id`            | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `label_id`      | integer        | yes (or `name`)                   | The id of the existing label     |
-| `name`          | string         | yes (or `label_id`)               | The name of the existing 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/projects/1/labels?name=bug"
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/bug"
 ```
 
+NOTE: **Note:** An older endpoint `DELETE /projects/:id/labels` with `name` in the params is still available, but deprecated.
+
 ## Edit an existing label
 
 Updates an existing label with new name or new color. At least one parameter
 is required, to update the label.
 
 ```
-PUT /projects/:id/labels
+PUT /projects/:id/labels/:label_id
 ```
 
 | Attribute       | Type    | Required                          | Description                      |
 | --------------- | ------- | --------------------------------- | -------------------------------  |
 | `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `label_id`      | integer | yes (or `name`)                   | The id of the existing label     |
-| `name`          | string  | yes (or `label_id`)               | The name of the existing label   |
+| `label_id` | integer or string | yes | The ID or title of a group's label. |
 | `new_name`      | string  | yes if `color` is not provided    | The new name of the label        |
 | `color`         | string  | yes if `new_name` is not provided | 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 new description of the label |
 | `priority`    | integer | no       | The new priority of the label. Must be greater or equal than zero or `null` to remove the priority. |
 
 ```bash
-curl --request PUT --data "name=documentation&new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels"
+curl --request PUT --data "new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/documentation"
 ```
 
 Example response:
@@ -187,6 +223,8 @@ Example response:
 }
 ```
 
+NOTE: **Note:** An older endpoint `PUT /projects/:id/labels` with `name` or `label_id` in the params is still available, but deprecated.
+
 ## Promote a project label to a group label
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/25218) in GitLab 12.3.
@@ -194,16 +232,16 @@ Example response:
 Promotes a project label to a group label.
 
 ```
-PUT /projects/:id/labels/promote
+PUT /projects/:id/labels/:label_id/promote
 ```
 
 | Attribute       | Type    | Required                          | Description                      |
 | --------------- | ------- | --------------------------------- | -------------------------------  |
 | `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `name`          | string  | yes                               | The name of the existing label   |
+| `label_id` | integer or string | yes | The ID or title of a group's label. |
 
 ```bash
-curl --request PUT --data "name=documentation" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/promote"
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/documentation/promote"
 ```
 
 Example response:
@@ -221,6 +259,8 @@ Example response:
 }
 ```
 
+NOTE: **Note:** An older endpoint `PUT /projects/:id/labels/promote` with `name` in the params is still available, but deprecated.
+
 ## Subscribe to a label
 
 Subscribes the authenticated user to a label to receive notifications.