BigW Consortium Gitlab

labels.md 6.89 KB
Newer Older
1 2 3 4
# Labels

## List labels

5
Get all labels for a given project.
6 7 8 9 10

```
GET /projects/:id/labels
```

11 12 13
| Attribute | Type    | Required | Description           |
| --------- | ------- | -------- | --------------------- |
| `id`      | integer | yes      | The ID of the project |
14 15

```bash
16
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/1/labels
17 18 19 20
```

Example response:

21 22
```json
[
23 24
   {
      "name" : "bug",
25
      "color" : "#d9534f",
26 27 28 29
      "description": "Bug reported by user",
      "open_issues_count": 1,
      "closed_issues_count": 0,
      "open_merge_requests_count": 1
30 31 32
   },
   {
      "color" : "#d9534f",
33
      "name" : "confirmed",
34 35 36 37
      "description": "Confirmed issue",
      "open_issues_count": 2,
      "closed_issues_count": 5,
      "open_merge_requests_count": 0
38 39 40
   },
   {
      "name" : "critical",
41
      "color" : "#d9534f",
42
      "description": "Critical issue. Need fix ASAP",
43 44 45
      "open_issues_count": 1,
      "closed_issues_count": 3,
      "open_merge_requests_count": 1
46 47 48
   },
   {
      "name" : "documentation",
49
      "color" : "#f0ad4e",
50 51 52 53
      "description": "Issue about documentation",
      "open_issues_count": 1,
      "closed_issues_count": 0,
      "open_merge_requests_count": 2
54 55 56
   },
   {
      "color" : "#5cb85c",
57
      "name" : "enhancement",
58 59 60 61
      "description": "Enhancement proposal",
      "open_issues_count": 1,
      "closed_issues_count": 0,
      "open_merge_requests_count": 1
62
   }
63 64 65 66 67
]
```

## Create a new label

68 69 70 71
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.
72 73 74 75 76

```
POST /projects/:id/labels
```

77 78 79 80 81 82
| 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 |
| `description` | string  | no       | The description of the label |
83 84

```bash
85
curl --data "name=feature&color=#5843AD" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
86
```
87

88
Example response:
89

90 91 92
```json
{
   "name" : "feature",
93 94
   "color" : "#5843AD",
   "description":null
95 96
}
```
97 98 99

## Delete a label

100 101 102 103 104
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.
105 106 107 108 109

```
DELETE /projects/:id/labels
```

110 111 112 113
| Attribute | Type    | Required | Description           |
| --------- | ------- | -------- | --------------------- |
| `id`      | integer | yes      | The ID of the project |
| `name`    | string  | yes      | The name of the label |
114

115
```bash
116
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels?name=bug"
117 118 119 120 121 122 123 124
```

Example response:

```json
{
   "title" : "feature",
   "color" : "#5843AD",
125
   "description": "New feature proposal",
126 127 128 129 130 131 132
   "updated_at" : "2015-11-03T21:22:30.737Z",
   "template" : false,
   "project_id" : 1,
   "created_at" : "2015-11-03T21:22:30.737Z",
   "id" : 9
}
```
Robert Schilling committed
133 134 135

## Edit an existing label

136
Updates an existing label with new name or new color. At least one parameter
Robert Schilling committed
137 138
is required, to update the label.

139 140 141 142
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.

Robert Schilling committed
143 144 145 146
```
PUT /projects/:id/labels
```

147 148 149 150 151 152 153
| 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 |
| `description`   | string  | no                                | The new description of the label |
154 155

```bash
156
curl --request PUT --data "name=documentation&new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
157
```
Robert Schilling committed
158

159
Example response:
Robert Schilling committed
160

161 162 163
```json
{
   "color" : "#8E44AD",
164 165
   "name" : "docs",
   "description": "Documentation"
166 167
}
```
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186

## Subscribe to a label

Subscribes the authenticated user to a label to receive notifications. If the
operation is successful, status code `201` together with the updated label is
returned. If the user is already subscribed to the label, the status code `304`
is returned. If the project or label is not found, status code `404` is
returned.

```
POST /projects/:id/labels/:label_id/subscription
```

| Attribute  | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `id`       | integer           | yes      | The ID of a project                  |
| `label_id` | integer or string | yes      | The ID or title of a project's label |

```bash
187
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/labels/1/subscription
188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
```

Example response:

```json
{
    "name": "Docs",
    "color": "#cc0033",
    "description": "",
    "open_issues_count": 0,
    "closed_issues_count": 0,
    "open_merge_requests_count": 0,
    "subscribed": true
}
```

## Unsubscribe from a label

Unsubscribes the authenticated user from a label to not receive notifications
from it. If the operation is successful, status code `200` together with the
updated label is returned. If the user is not subscribed to the label, the
status code `304` is returned. If the project or label is not found, status code
`404` is returned.

```
DELETE /projects/:id/labels/:label_id/subscription
```

| Attribute  | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `id`       | integer           | yes      | The ID of a project                  |
| `label_id` | integer or string | yes      | The ID or title of a project's label |

```bash
222
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/labels/1/subscription
223 224 225 226 227 228 229 230 231 232 233 234 235 236 237
```

Example response:

```json
{
    "name": "Docs",
    "color": "#cc0033",
    "description": "",
    "open_issues_count": 0,
    "closed_issues_count": 0,
    "open_merge_requests_count": 0,
    "subscribed": false
}
```