Labels
This Public Stable API gets, creates, updates, and deletes labels.
Labels API Methods
Functionality | HTTP | URI |
|---|---|---|
Get a collection of labels. |
|
|
Get an individual label. |
|
|
Create a label |
|
|
Update a label |
|
|
Delete a label |
|
|
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 returned on a GET collection of labels is 500.
Note
GET returns any label that contains a match instead of 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 not creating labels with names similar to these default system labels to avoid 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]