Label

Labels are pre-defined or custom key / value pairs that can be tied to elements for easy recognition and selection.

The following elements in the platform can have labels:

Structure

Property	Value type	Required	Description
key	string	Yes	The name of the label
value	string	Yes	The value of the label

Table 1: Label element structure

Requirements

A Label element has the following constraints:

allowed characters in the label key are a-z 0-9 _ -
the label key may be no longer than 50 characters
the label value may be no longer than 150 characters

Adding & updating labels

Labels in the ApplicationBuild and ApplicationInstance elements are stored as an array of Label elements:

PUT /applicationInstance/{applicationInstanceId}

{
  "labelPublic": [
    {
      "key": "label1",
      "value": "A value"
    },
    {
      "key": "label2",
      "value": "Another value"
    }
  ]
}

Figure 1: Example labels for an ApplicationInstance element

When you want to add a new label, you can PUT an element with only that new label. You would submit:

PUT /applicationInstance/{applicationInstanceId}

{
  "labelPublic": [
    {
      "key": "label3",
      "value": "A new value"
    }
  ]
}

Figure 2: Example of adding a new label to an ApplicationInstance element

The result will be that the element has 3 labels: label1, label2 and label3.

When you want to update a label, you only have to submit that one label for the element:

PUT /applicationInstance/{applicationInstanceId}

{
  "labelPublic": [
    {
      "key": "label2",
      "value": "An updated value"
    }
  ]
}

Figure 3: Example of updating an existing label of an ApplicationInstance element

Deleting a label is done by submitting a label with a null value:

PUT /applicationInstance/{applicationInstanceId}

{
  "labelPublic": [
    {
      "key": "label2",
      "value": null
    }
  ]
}

Figure 4: Example of deleting a label from an ApplicationInstance element

After these example mutations, the element ends up with the following labels:

GET /applicationInstance/{applicationInstanceId}

{
  "labelPublic": [
    {
      "key": "label1",
      "value": "A value"
    },
    {
      "key": "label3",
      "value": "A new value"
    }
  ]
}

Figure 5: The resulting labels for an ApplicationInstance element after applying the examples

Pre-defined labels

For ApplicationInstance elements, the platform creates a number of default labels (platform defined labels):

application_id
fleet_id
host_id
dc_location_id
region_id
region_name
application_build_id

These labels are always present for all ApplicationInstance elements. It does mean that user-defined labels cannot have the same name as platform defined labels. These names are reserved.

Using labels

Labels can be used to trim selections of elements.

In the API v3, using labels is done by adding a label expression as an URL query parameter.

An example of a label expression:

region_id=123 and fleet_id=456 or host_id=46256

When used in an API v3 request the expression must be url encoded:

GET /applicationInstance?labels=region_id%3D123%20and%20fleet_id%3D456%20or%20host_id%3D46256

If you filter on region_name (or any other label with a string value) you must wrap the search value in double quotes:

region_name="Rotterdam"

The url encoded request:

GET /applicationInstance?labels=region_name%3D%22Rotterdam%22