From 981a6865f2fa6185eb3f9bc746f5fb60badf8f09 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 18 Jan 2016 09:41:42 +0100 Subject: Refactor labels API documentation [ci skip] --- doc/api/labels.md | 152 +++++++++++++++++++++++++++++++++++++++--------------- 1 file 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" +} +``` -- cgit v1.2.1