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 of labels returned in a GET collection is 500.
Note
GET returns any label containing a match, rather than an exact one. 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 built-in environment, application, and location labels defined as "All" that create broad policies to cover all applications, environments, and 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]
Label Groups
This Public Stable API helps you write rules more efficiently if the same labels are used repeatedly in rulesets. When you add labels to a label group, the label group can be used in a rule or ruleset scope to represent multiple labels. A label group can also be a member (child) of other label groups.
Label Groups API Methods
Functionality | HTTP | URI |
|---|---|---|
Get a collection of label groups. |
|
|
Get an individual label group. |
|
|
Get an individual label group to see if it is a member of other label groups. |
|
|
Create a new label group. |
|
|
Update an individual label group. |
|
|
Delete an individual label grou.p |
|
|
Active vs. Draft
Get a Collection of Label Groups
This method gets all label groups in your organization. Use this to discover the label_group_id to GET a specific label group or for POST, PUT, and DELETE operations.
By default, the maximum number returned on a GET collection of label groups is 500. If you want to get more than 500 label groups, use Asynchronous GET Collections.
URI to Get a Collection of Label Groups
GET [org_href]/sec_policy/draft/label_groups
URI to Get an Individual Label
GET [label_group_href]
Label Group Belonging to Other Groups
This method determines if an individual label group is a member of other label groups. For example, if one label group is also a “child” of three other label groups, the response to this call returns the three “parent” label groups to which the specified label group belongs.
URI to Check if a Label Group Belongs to Other Label Groups
GET [api_version][label_group_href]/member_of
Response
If the specified label group does not belong to any other label groups, the call returns an HTTP 200 message. If the specified label group belongs to other label groups, the response lists the parent label groups. For example:
[
{
"href": "/orgs/7/sec_policy/draft/label_groups/b51c986b-db35-47d4-ab77-aae570d1f164",
"name": "MyLablesUS"
}
]Update a Label Group
To update an individual label group, use the HREF of the label group, which is obtained from an API call to get a collection of label groups.
URI to Update a Label Group
PUT [label_group_href]
Delete a Label Group
To delete an individual label group, specify the HREF of the label group you want to delete. The HREF is obtained from an API call to get a collection of label groups.
URI to Delete a Label Group
DELETE [api_version][label_group_href]