# Component Labels REST API

The Component Labels API allows you to manage component labels for applications, organizations, and repositories.

A component label consists of a label, a color, and an optional description.

Valid values for the field color are:

```
light-red, light-green, light-blue, light-purple, dark-red, dark-green, dark-blue, dark-purple, orange, yellow
```

## Creating Component Labels

1. To create a component label for an application, use a POST request and specify the applicationId.
   
   ```
   POST /api/v2/labels/application/{applicationId}
   ```

2. To create component label for an organization, use a POST request and specify the organizationId.
   
   ```
   POST /api/v2/labels/organization/{organizationId}
   ```

3. To create a component label for a repository, use a POST request and specify the repositoryId.
   
   ```
   POST /api/v2/labels/repository/{repositoryId}
   ```

### Example

```
curl -u admin:admin123 -X POST -H 'Content-Type: application/json' 'http://localhost:8070/api/v2/labels/application/787c2e3dc8e745c48743926251eef00b' -d '{"label": "New Label","color": "dark-blue","description": "High Risk"}'
```

where 787c2e3dc8e745c48743926251eef00b is the applicationId.

### Response

Returns HTTP 200 code on successful creation echoing the created label with its details including the assigned component label Id.

```
{
  "id": "8fadd58097cc49d7bdd5ecf38c33fb0a",
  "label": "New Label",
  "description": "High Risk",
  "color": "dark-blue",
  "ownerId": "787c2e3dc8e745c48743926251eef00b",
  "ownerType": "APPLICATION"
}
```

## Querying Component Labels

1. To retrieve details for component labels for an application, use a `GET` request and specify the application ID.
   
   ```
   GET /api/v2/labels/application/{applicationId}
   ```

2. To retrieve details for component labels for an organization, use a `GET` request and specify the organization ID.
   
   ```
   GET /api/v2/labels/organization/{organizationId}
   ```

3. To retrieve details for component labels for a repository, use a `GET` request and specify the repository ID.
   
   ```
   GET /api/v2/labels/repository/{repositoryId}
   ```

### Example

```
curl -u admin:admin123 'http://localhost:8070/api/v2/labels/application/787c2e3dc8e745c48743926251eef00b'
```

where 787c2e3dc8e745c48743926251eef00b is the application Id.

### Response

Returns HTTP 200 code on successful query and returns an array of component labels for the application:

```
[
  {
    "id": "3365f8827f9a4ce091352b91d58adf0f",
    "label": "New Label",
    "description": "High Risk",
    "color": "dark-blue",
    "ownerId": "787c2e3dc8e745c48743926251eef00b",
    "ownerType": "APPLICATION"
  }
]
```

4. To retrieve details for **inherited component labels** for an application, use the query parameter `inherit.`

### Example

```
curl -u admin:admin123 'http://localhost:8070/api/v2/labels/application/787c2e3dc8e745c48743926251eef00b?inherit=true'
```

### Response

Returns HTTP 200 code on successful query and labels from the application's inheritance tree:

```
[
  {
    "id": "3365f8827f9a4ce091352b91d58adf0f",
    "label": "New Label",
    "description": "High Risk",
    "color": "dark-blue",
    "ownerId": "787c2e3dc8e745c48743926251eef00b",
    "ownerType": "APPLICATION"
  },
  {
    "id": "d50ffc5f3b904570a7633d26157c2890",
    "label": "Architecture-Blacklisted",
    "description": "Components which have been blacklisted from use",
    "color": "orange",
    "ownerId": "ROOT_ORGANIZATION_ID",
    "ownerType": "ORGANIZATION"
  }
]
```

The label Architecture-Blacklisted is owned by ROOT_ORGANIZATION which is inherited by this application.

5. To retrieve details for applicable component labels for application, use a GET request with query parameter applicable.

### Example

```
curl -u admin:admin123 'http://localhost:8070/api/v2/labels/application/app-1/applicable'
```

### Response

Returns HTTP 200 code on successful query and labels that are applicable to the application.

```
{
  "labelsByOwner": [
    {
      "ownerId": "d56907ab10764cff869cba4fa4baf525",
      "ownerName": "sample-app-1",
      "ownerType": "application",
      "labels": [
        {
          "id": "e7a421214d2d4e58869e0b7f9754972b",
          "label": "application-label-1",
          "description": "label on application level component",
          "color": "dark-green",
          "ownerId": "d56907ab10764cff869cba4fa4baf525",
          "ownerType": "APPLICATION"
        }
      ]
    },
    {
      "ownerId": "fba8e4e688414d71aa922eb669b1267e",
      "ownerName": "sample-org-1",
      "ownerType": "organization",
      "labels": []
    },
    {
      "ownerId": "ROOT_ORGANIZATION_ID",
      "ownerName": "Root Organization",
      "ownerType": "organization",
      "labels": [
        {
          "id": "d5c57783d06b4fb781ee91cf6e4d4b84",
          "label": "Architecture-Blacklisted",
          "description": "Components which have been blacklisted from use",
          "color": "orange",
          "ownerId": "ROOT_ORGANIZATION_ID",
          "ownerType": "ORGANIZATION"
        },
        {
          "id": "e377ead274134acbb75b861a957ced28",
          "label": "Architecture-Cleanup",
          "description": "Components which are relics of a build and should not be included in the distribution",
          "color": "orange",
          "ownerId": "ROOT_ORGANIZATION_ID",
          "ownerType": "ORGANIZATION"
        },
        {
          "id": "9a13ebf7e36449aa9e3f56bd7c76b840",
          "label": "Architecture-Deprecated",
          "description": "Components we want to discourage from developer use",
          "color": "orange",
          "ownerId": "ROOT_ORGANIZATION_ID",
          "ownerType": "ORGANIZATION"
        }
      ]
    }
  ]
}
```

## Updating Component Labels

To update and existing component label for an application, use the PUT request and specify the applicationID

```
PUT /api/v2/labels/application/{applicationId}
```

To update an existing component label for an organization, use the PUT request and specify the organizationID

```
PUT /api/v2/labels/organization/{organizationId}
```

To update an existing component label for a repository, use the PUT request and specify the repositoryId

```
PUT /api/v2/labels/repository/{repositoryId}
```

### Example

```
curl -u admin:admin123 -X PUT -H 'Content-Type: application/json' 'http://localhost:8070/api/v2/labels/application/787c2e3dc8e745c48743926251eef00b' -d '{"id": "3365f8827f9a4ce091352b91d58adf0f", "label": "Updated Label","color": "dark-red","description": "New Description"}'
```

where 3365f8827f9a4ce091352b91d58adf0f is the component label Id and 787c2e3dc8e745c48743926251eef00b is the application Id.

### Response

Returns HTTP 200 code on successful creation echoing the created label.

## Deleting Component Labels

1. To delete an application label, use a `DELETE` request and specify the application Id and label Id.

A component label for an application can be deleted by sending a `DELETE` request to

```
DELETE api/v2/labels/application/{applicationId}/{labelId}
```

2. To delete an organization label, use a `DELETE` request and specify the organization ID and label ID.

```
DELETE /api/v2/labels/organization/{organizationId}/{labelId}
```

3. To delete a repository label, use a `DELETE` request and specify the repository ID and label ID.

```
DELETE /api/v2/labels/repository/{repositoryId}/{labelId}
```

### Example

```
curl -u admin:admin123 -X DELETE 'http://localhost:8070/api/v2/labels/application/787c2e3dc8e745c48743926251eef00b/3365f8827f9a4ce091352b91d58adf0f'
```

where 787c2e3dc8e745c48743926251eef00b is the application id and `3365f8827f9a4ce091352b91d58adf0f` is the label ID.

### Response

The server responds with a `204 No Content` upon successful deletion.

## Assign Component Labels

1. To assign a component label to an application, use the POST request and specify the component hash, label name, and the application ID.

```
POST /api/v2/components/{componentHash}/labels/{labelName}/applications/{applicationId}
```

where componentHash is the sha 1 hash from the source repository, lablelName is an existing label name and applicationId is the internal application ID.

2. To assign a component labels to an organization, use the POST request and specify the component hash, label name, and the organization ID.

```
POST /api/v2/components/{componentHash}/labels/{labelName}/organizations/{organizationId}
```

### Example

An example assigning the application component label "Architecture-Deprecated":

```
curl -u admin:admin123 -X POST 'http://localhost:8070/api/v2/components/1249e25aebb15358bedd/labels/Architecture-Deprecated/applications/5065550c24514129bf66f9afd5c7be60'
```

where 1249e25aebb15358bedd is the component hash, Architecture-Deprecated is the label name, and 5065550c24514129bf66f9afd5c7be60 is the application ID.

### Response

The server will respond with a 204 status upon success.

## Unassign Component Labels

1. To unassign or remove a component label from an application, use the DELETE request and specify the component hash, label name, and internal application ID.

```
DELETE /api/v2/components/{componentHash}/labels/{labelName}/applications/{applicationId}
```

2. To unassign or remove a component label from an organization, use the DELETE request and specify the component hash, label name, and internal organization ID.

```
DELETE /api/v2/components/{componentHash}/labels/{labelName}/organizations/{organizationId}
```

**NOTE:** This operation only deletes the component labels defined at the organization level. Component labels that have been assigned in the context of individual applications within the organization are not affected.

### Example

An example removing the application component label "Architecture-Deprecated":

```
curl -u admin:admin123 -X DELETE 'http://localhost:8070/api/v2/components/1249e25aebb15358bedd/labels/Architecture-Deprecated/applications/5065550c24514129bf66f9afd5c7be60'
```

where

1249e25aebb15358bedd is the component hash,

Architecture-Deprecated is the label name, and 5065550c24514129bf66f9afd5c7be60 is the application Id.

### Response

The server will respond with a 204 status upon success.