Refactor labels API documentation [ci skip]doc_refactor_labels_api

1 files changed, 111 insertions, 41 deletions

diff --git a/doc/api/labels.md b/doc/api/labels.md
index de41f35d284..6496ffe9fd1 100644
--- a/doc/api/labels.md
+++ b/doc/api/labels.md
@@ -2,83 +2,153 @@
 
 ## List labels
 
-Get all labels for given project.
+Get all labels for a given project.
 
 ```
 GET /projects/:id/labels
 ```
 
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/1/labels
+```
+
+Example response:
+
 ```json
 [
-    {
-        "name": "Awesome",
-        "color": "#DD10AA"
-    },
-    {
-        "name": "Documentation",
-        "color": "#1E80DD"
-    },
-    {
-        "name": "Feature",
-        "color": "#11FF22"
-    },
-    {
-        "name": "Bug",
-        "color": "#EE1122"
-    }
+   {
+      "name" : "bug",
+      "color" : "#d9534f"
+   },
+   {
+      "color" : "#d9534f",
+      "name" : "confirmed"
+   },
+   {
+      "name" : "critical",
+      "color" : "#d9534f"
+   },
+   {
+      "color" : "#428bca",
+      "name" : "discussion"
+   },
+   {
+      "name" : "documentation",
+      "color" : "#f0ad4e"
+   },
+   {
+      "color" : "#5cb85c",
+      "name" : "enhancement"
+   },
+   {
+      "color" : "#428bca",
+      "name" : "suggestion"
+   },
+   {
+      "color" : "#f0ad4e",
+      "name" : "support"
+   }
 ]
 ```
 
 ## Create a new label
 
-Creates a new label for given repository with given name and color.
+Creates a new label for the given repository with the given name and color.
+
+It returns 200 if the label was successfully created, 400 for wrong parameters
+and 409 if the label already exists.
 
 ```
 POST /projects/:id/labels
 ```
 
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID of the project |
+| `name`    | string  | yes | The name of the label |
+| `color`   | string  | yes | The color of the label in 6-digit hex notation with leading `#` sign |
+
+```bash
+curl --data "name=feature&color=#5843AD" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
+```
 
-- `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)
+Example response:
 
-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, 400 and an explaining error message is returned.
+```json
+{
+   "name" : "feature",
+   "color" : "#5843AD"
+}
+```
 
 ## Delete a label
 
-Deletes a label given by its name.
+Deletes a label with a given name.
+
+It returns 200 if the label was successfully deleted, 400 for wrong parameters
+and 404 if the label does not exist.
+In case of an error, an additional error message is returned.
 
 ```
 DELETE /projects/:id/labels
 ```
 
-- `id` (required) - The ID of a project
-- `name` (required) - The name of the label to be deleted
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID of the project |
+| `name`    | string  | yes | The name of the label |
 
-It returns 200 if the label successfully was deleted, 400 for wrong parameters
-and 404 if the label does not exist.
-In case of an error, additionally an error message is returned.
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels?name=bug"
+```
+
+Example response:
+
+```json
+{
+   "title" : "feature",
+   "color" : "#5843AD",
+   "updated_at" : "2015-11-03T21:22:30.737Z",
+   "template" : false,
+   "project_id" : 1,
+   "created_at" : "2015-11-03T21:22:30.737Z",
+   "id" : 9
+}
+```
 
 ## Edit an existing label
 
-Updates an existing label with new name or now color. At least one parameter
+Updates an existing label with new name or new color. At least one parameter
 is required, to update the label.
 
+It returns 200 if the label was successfully deleted, 400 for wrong parameters
+and 404 if the label does not exist.
+In case of an error, an additional error message is returned.
+
 ```
 PUT /projects/:id/labels
 ```
 
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID of the project |
+| `name`    | string  | yes | The name of the existing label |
+| `new_name` | string  | yes if `color` if not provided | The new name of the label |
+| `color`   | string  | yes if `new_name` is not provided | The new color of the label in 6-digit hex notation with leading `#` sign |
+
+```bash
+curl -X PUT --data "name=documentation&new_name=docs&color=#8E44AD" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
+```
 
-- `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)
+Example response:
 
-On success, this method returns 200 with the updated label.
-If required parameters are missing or parameters are invalid, 400 is returned.
-If the label to be updated is missing, 404 is returned.
-In case of an error, additionally an error message is returned.
+```json
+{
+   "color" : "#8E44AD",
+   "name" : "docs"
+}
+```