Skip to main content

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}

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

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.