Component Labels REST API - v2

NEW IN RELEASE 1.48

The Component Labels API manages component labels for applications, organizations, and repositories as well as allowing you to assign them to or remove them from applications and organizations. 

Managing Component Labels

NEW IN RELEASE 90

A component label consists of a label (required), a color (required) and a description (optional). Possible 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 Application Component Labels

A component label for an application can be created by sending a POST request to

POST /api/v2/labels/application/{applicationId}

with a body specifying the label's details.

As an example, in order to create a component label using cURL for the application with id 787c2e3dc8e745c48743926251eef00b the command would be as follows:

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"}'

The server responds with a 200 OK upon successful creation echoing the created label with its details including the assigned id 

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

Creating Organization and Repository Component Labels

A component label can be created for an organization or a repository by replacing the application in the path mentioned above either by an organization or a repository and using the id of the relevant owner as follows: 

POST /api/v2/labels/organization/{organizationId}
POST /api/v2/labels/repository/{repositoryId}

The payload required to be sent and the response will not be different. 

Querying Application Component Labels

Component labels for an application can be queried by sending a GET request to

GET /api/v2/labels/application/{applicationId}

As an example, in order to query component labels using cURL for the application with id 787c2e3dc8e745c48743926251eef00b the command would be as follows:

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

The server responds with a 200 Success upon 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"
  }
]

This endpoint also supports the query parameter inherit. If inherit is set to true, in addition to component labels owned by this application, component labels inherited from its parents are also returned. Issuing the example above with inherit set to true would be as follows:

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

which returns 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"
  }
]

Note above, the label Architecture-Blacklisted is owned by ROOT_ORGANIZATION. That is an example of an inherited component label.

Querying Organization and Repository Component Labels

Component labels can be queried for an organization or a repository by replacing the application in the path mentioned above either by an organization or a repository and using the id of the relevant owner as follows: 

POST /api/v2/labels/organization/{organizationId}
POST /api/v2/labels/repository/{repositoryId}

Both paths also support inherit and the returned result will again be a list of labels.

Updating Application Component Labels

A component label for an application can be updated by sending a PUT request to

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

with a body specifying the label's details including the label id.

As an example, in order to update a component label with id 3365f8827f9a4ce091352b91d58adf0f using cURL for the application with id 787c2e3dc8e745c48743926251eef00b the command would be as follows:

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"}'

The server responds with a 200 OK upon successful update echoing the created label.

Updating Organization and Repository Component Labels

A component label can be updated for an organization or a repository by replacing the application in the path mentioned above either by an organization or a repository and using the id of the relevant owner as follows: 

PUT /api/v2/labels/organization/{organizationId}
PUT /api/v2/labels/repository/{repositoryId}

The payload required to be sent and the response will not be different. 

Deleting Application Component Labels

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

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

As an example, in order to delete a component label using cURL for the application with id 787c2e3dc8e745c48743926251eef00b and the label with id 3365f8827f9a4ce091352b91d58adf0f the command would be as follows:

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

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

Deleting Organization and Repository Component Labels

A component label can be deleted for an organization or a repository by replacing the application in the path mentioned above either by an organization or a repository and using the id of the relevant owner as follows: 

PUT /api/v2/labels/organization/{organizationId}/{labelId}
PUT /api/v2/labels/repository/{repositoryId}/{labelId}

Assigning Component Labels

Assigning Application Component Labels

Assigning an application component label requires the component hash, label name, and internal application ID for the component label.

Construct a POST REST request with the following path:

  • componentHash - A sha1 hash of the component, which can be found in the source repository.
  • labelName - The name of an existing label that can be applied to the application.
  • applicationId - The internal ID of the application. Obtained from an 'applications' REST API call with: GET /api/v2/applications?publicId={YourPublicId}.
POST /api/v2/components/{componentHash}/labels/{labelName}/applications/{applicationId}

The server will respond with a 204 status upon success.

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'

Assigning Organization Component Labels 

NEW IN RELEASE 81

Component labels can also be assigned at the level of an organization in which case the component label is visible to all applications within that organization. The REST request for this operation is mostly identical to the one above for applications apart from the last path segments that rather denote the target organization instead of an application:

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

To obtain the ID of the organization, you can use the organization REST API.

Removing Application Component Labels

Removing an application component label requires the component hash, label name, and internal application ID for the component label.

Construct a DELETE REST request with the following path:

  • componentHash - A sha1 hash of the component, which can be found in the source repository.
  • labelName - The name of an existing label that can be applied to the application.
  • applicationId - The internal ID of the application. Obtained from an 'applications' REST API call.
DELETE /api/v2/components/{componentHash}/labels/{labelName}/applications/{applicationId}

The server will respond with a 204 status upon success.

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'

Removing Organization Component Labels 

NEW IN RELEASE 81

A component label that was assigned for an entire organization can be removed pretty much the same way as one for an application. The only difference to the above case is the specification of an organization ID instead of an application ID:

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

Note that this operation strictly only changes the given organization and its very own component labels. Component labels that have been assigned in the context of individual applications within the organization are not affected.