Labels

This Public Stable API gets, creates, updates, and deletes labels.

Labels API Methods

Functionality	HTTP	URI
Get a collection of labels.	`GET`	`[api_version][org_href]/labels`
Get an individual label.	`GET`	`[api_version][label_href]`
Create a label	`POST`	`[api_version][org_href]/labels`
Update a label	`PUT`	`[api_version][label_href]`
Delete a label	`DELETE`	`[api_version][label_href]`

Get Labels

This API returns all labels in an organization or a single label. When you get labels, they are returned in the form of an HREF path property, for example: "/orgs/2/labels/1662"

By default, the maximum number of labels returned in a GET collection is 500.

Note

GET returns any label that contains a match, rather than an exact match. For example, a GET request for labels with value=APP could return APP, WEB-APP, and WEBAPP.

URI to Get Collection of Labels

GET [api_version][org_href]/labels

URI to Get an Individual Label

GET [api_version][label_href]

Create a Label

This API creates a new label inside an organization for one of the following label types, for which you can provide your string value:

Application (“app”): The type of application the workload supports. Examples are HRM, SAP, Finance, and Storefront.
Role (“role”): The function of a workload. A simple two-tier application consisting of a web server and a database server has two roles: Web and Database.
Environment (“env”): The stage in the development of the application. For example, production, QA, development, and staging.
Location (“loc”): The location of the workload. For example, Germany, the US, Europe, and Asia; or Rack #3, Rack #4, Rack #5; or data center, AWS-east1, AWS-east2, and so on.

System Default “All” for Labels

The PCE provides a built-in environment, application, and location labels defined as "All" that create broad policies to cover all applications, all environments, and all locations.

For this reason, you cannot create labels of these types defined as "All Applications," "All Environments," or "All Locations" (exactly as written in quotes) to prevent confusion for policy writers.

If you attempt to create labels of these types with the exact name as the system defaults (for example, "All Applications"), you receive an HTTP "406 Not Acceptable" error.

Illumio recommends avoiding the creation of labels with names similar to these default system labels to prevent confusion.

URI to Create a Label

POST [api_version][org_href]/labels

Update a Label

This API allows you to update a label applied to a workload, given that you have the label HREF, which is returned when you get all labels in an organization. For example: "/orgs/2/labels/1662"

URI to Update a Label

PUT [api_version][label_href]

Delete a Label

This API deletes a label from an organization using the label HREF, which is returned when you get a collection of labels in an organization. For example: "/orgs/2/labels/1662"

URI to Delete a Label

DELETE [api_version][label_href]

Labels Reference

This topic provides properties, parameters, and examples for labels.

Query parameters for labels

Parameter	Description	Type	Required
`org_id`	Organization ID	Integer	Yes
`external_data_reference`	A unique identifier within the external data source	String	No
`external_data_set`	The data source from which a resource originates	String	No
`include_deleted`	Include deleted labels	Boolean	No
`key`	Key by which to filter	String	GET: No POST: Yes
`max_results`	Maximum number of labels to return.	Integer	No
`usage`	Indicate label usage, including if the label is currently used in an RBAC scope for user permissions if the label is applied to a workload, virtual service, Pairing Profile, selective enforcement, virtual server, or ruleset, and if the label belongs to a label group.	Boolean	No
`value`	Value on which to filter. Supports partial matches.	String	GET, PUT: No POST: Yes
`label_id`	Label ID, for `[api_version][label_href]`	Integer	Yes

Properties for labels

Property	Description	Type
`key`	Key in key-value pair	String
`value`	Value in key-value pair",	String
`href`	Label URI
`updated_at`	Timestamp when this label was last updated	String
`created_at`	Timestamp when this label was first created	String
`external_data_reference`	A unique identifier within the external data source	String, Null
`external_data_set`	The data source from which a resource originates	String, Null

Curl Command to Get Collection of Labels

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/labels -H "Accept: application/json" -u $KEY:$TOKEN

Response Body

In the response body, each label returned is identified as an HREF, for example: "/orgs/2/labels/1662"

For example:

 {
          href: "/orgs/2/labels/1662"
          key: "env"
          value: "Prod"
          created_at: "2020-01-22T18:24:33Z"
          updated_at: "2020-01-22T18:24:40Z"
          created_by: {
             href: "/users/9"
          }
          updated_by: {
             href: "/users/9"
          }
     }
     {
          href: "/orgs/2/labels/1128"
          key: "role"
          value: "DB"
          created_at: "2020-01-22T18:24:53Z"
          updated_at: "2020-01-22T18:24:59Z"
          created_by: {
              href: "/users/9"
         }
          updated_by: {
              href: "/users/9"
         }
     }

Curl Command to Get a Label

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/labels/8 -H "Accept: application/json" -u $KEY:$TOKEN

Response Body

{
     href: "/orgs/2/labels/8"
     key: "env"
     value: "Prod"
     created_at: "2020-01-22T18:24:33Z"
     updated_at: "2020-01-22T18:24:40Z"
     created_by: {
          href: "/users/9"
     }
     updated_by: {
          href: "/users/9"
     }
}

An example request body to create a label

{
   "key":"role",
   "value":"web"
}

Curl Command to Create a Label

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/2/labels -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"key":"role","value":"web"}'

Response Body

The created label is in the form of an HREF path property. For example, in the response below, the label is identified as "/orgs/2/labels/1677".

{
     href: "/orgs/2/labels/1677"
     key: "role"
     value: "my_web_app"
     created_at: "2014-04-18T19:39:27Z"
     updated_at: "2014-04-18T19:39:27Z"
     created_by: {
         href: "/users/76"
     }
     updated_by: {
         href: "/users/76"
     }
}

An example request body to update a label

To update a label definition, the JSON request body can be constructed as follows:

{ "value":"db" }

Curl Command to Update a Label

curl -X PUT https://pce.my-company.com:8443/api/v2/orgs/2/labels/1662 -H "Accept: application/json" -u $KEY:$TOKEN -d '{"value":"db"}

Curl Command to Delete a Label

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/labels/1662 -H "Accept: application/json" -u $KEY:$TOKEN

REST APIs 25.1 Developer Guide

Labels

Labels API Methods

Get Labels

Note

Create a Label

System Default “All” for Labels

Update a Label

Delete a Label

Labels Reference

Query parameters for labels

Properties for labels

An example request body to create a label

Search results