Merge pull request #7479 from Razer6/feature/labels_api

Implement complete labels API (create/delete/update)

3 files changed, 86 insertions, 26 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index a0a9ba6f4b6..44e95ed8258 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -12,6 +12,7 @@
 - [Branches](branches.md)
 - [Merge Requests](merge_requests.md)
 - [Issues](issues.md)
+- [Labels](labels.md)
 - [Milestones](milestones.md)
 - [Notes](notes.md) (comments)
 - [Deploy Keys](deploy_keys.md)
diff --git a/doc/api/labels.md b/doc/api/labels.md
new file mode 100644
index 00000000000..95fd4e84119
--- /dev/null
+++ b/doc/api/labels.md
@@ -0,0 +1,85 @@
+# Labels
+
+## List labels
+
+Get all labels for given project.
+
+```
+GET /projects/:id/labels
+```
+
+```json
+[
+    {
+        "name": "Awesome",
+        "color": "#DD10AA"
+    },
+    {
+        "name": "Documentation",
+        "color": "#1E80DD"
+    },
+    {
+        "name": "Feature",
+        "color": "#11FF22"
+    },
+    {
+        "name": "Bug",
+        "color": "#EE1122"
+    }
+]
+```
+
+## Create a new label
+
+Creates a new label for given repository with given name and color.
+
+```
+POST /projects/:id/labels
+```
+
+Parameters:
+
+- `id` (required) - The ID of a project
+- `name` (required) - The name of the label
+- `color` (required) -  Color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB)
+
+It returns 200 and the newly created label, if the operation succeeds.
+If the label already exists, 409 and an error message is returned.
+If label parameters are invalid, 405 and an explaining error message is returned.
+
+## Delete a label
+
+Deletes a label given by its name.
+
+```
+DELETE /projects/:id/labels
+```
+
+- `id` (required) - The ID of a project
+- `name` (required) - The name of the label to be deleted
+
+It returns 200 if the label successfully was deleted, 404 for wrong parameters
+and 400 if the label does not exist.
+In case of an error, additionally an error message is returned.
+
+## Edit an existing label
+
+Updates an existing label with new name or now color. At least one parameter
+is required, to update the label.
+
+```
+PUT /projects/:id/labels
+```
+
+Parameters:
+
+- `id` (required) - The ID of a project
+- `name` (required) - The name of the existing label
+- `new_name` (optional) - The new name of the label
+- `color` (optional) -  New color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB)
+
+On success, this method returns 200 with the updated label.
+If required parameters are missing, 400 is returned.
+If the label to be updated is missing, 404 is returned.
+If parameters are invalid, 405 is returned. In case of an error,
+additionally an error message is returned.
diff --git a/doc/api/projects.md b/doc/api/projects.md
index b8876e8e104..894c2fd76a4 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -632,29 +632,3 @@ 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
-
-
-## Labels
-
-### List project labels
-
-Get a list of project labels.
-
-```
-GET /projects/:id/labels
-```
-
-Parameters:
-
-+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
-
-```json
-[
-  {
-    "name": "feature"
-  },
-  {
-    "name": "bug"
-  }
-]
-```