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`	`[api_version][org_href]/sec_policy/draft/label_groups`
Get an individual label group.	`GET`	`[api_version][label_group_href]`
Get an individual label group to see if it is a member of other label groups.	`GET`	`[api_version][label_group_href]/member_of`
Create a new label group.	`POST`	`[api_version][org_href]/sec_policy/draft/label_groups`
Update an individual label group.	`PUT`	`[api_version][label_group_href]`
Delete an individual label grou.p	`DELETE`	`[api_version][label_group_href]`

Active vs. Draft

This API operates on provisionable objects, which exist in either a draft (not provisioned) state or an active (provisioned) state.

Provisionable items include label groups, services, rulesets, IP lists, virtual services, firewall settings, enforcement boundaries, and virtual servers. For these objects, the URL of the API call must include the element called :pversion, which can be set to either draft or active.

Depending on the method, the API follows these rules:

For GET operations — :pversion can be draft, active, or the ID of the security policy.
For POST, PUT, DELETE — :pversion can be draft (you cannot operate on active items) or the ID if the security policy.

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, which 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]

Label Groups Reference

This topic provides properties, parameters, and examples for label groups.

Query parameters for label groups

Parameter	Description	Type	Required
`org_id`	Organization	Integer	Yes
`pversion`	Security Policy Version	String	Yes
`label_group_id`	Label Group UUID, for `[api_version][label_group_href]` and `[api_version][label_group_href]/member_of`	String	Yes
`usage`	Include label usage flags.	Boolean	No

Properties for label groups

Property	Description	Type
`href`	URI of this label group	String
`name`	The specific name of a label group to return. Supports partial matches	String
`key`	Key by which to filter	String
`created_at`	Timestamp when this label group was first created	String date/time
`updated_at`	Timestamp when this label group was last updated	String date/time
`deleted_at`	Timestamp when this label group was deleted	String, null
`created_by`	The user who originally created this label group "$ref": "../common/href_object.schema.json"
`updated_by`	The user who last updated this label group "$ref": "../common/href_object.schema.json"
`deleted_by`	Users who deleted this label group "$ref": "../common/href_object.schema.json"	Null
`blocked_connection_reject_scopes`	Label Group is referenced by Blocked Connection Reject Scopes. Replaces the property `blocked_connection_reject_scope`	Boolean
`loopback_interfaces_ in_policy_scopes`	Label Group is referenced by Loopback Interfaces in Policy Scopes.	Boolean
`ip_forwarding_enabled_scopes`	IP Forwarding Enabled Scopes reference Label Group.	Boolean

Curl Command to Get Label Groups

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

Response

When you get a collection of label groups, each label group is identified by an HREF. You need the HREF to update or delete an individual label group using the API.

{
    "href": "/orgs/2/sec_policy/draft/label_groups/4c8e3325-c6dd-4dc2-aadc-971e9de270e4",
    "created_at": "2020-07-25T00:46:52.552Z",
    "updated_at": "2020-07-25T00:59:00.177Z",
    "deleted_at": null,
    "created_by": {
      "href": "/users/3"
    },
    "updated_by": {
      "href": "/users/3"
    },
    "deleted_by": null,
    "name": "AppGroup1",
    "description": null,
    "key": "app",
    "labels": [],
    "sub_groups": [
      {
        "href": "/orgs/2/sec_policy/draft/label_groups/9b30081e-e105-44d8-9945-4c8a30dbe849",
        "name": "AppGroup3"
      }
    ]
  },

Request body to update a label group

This example request body updates the labels contained within a label group.

{
  "labels": [
    { "href": "/orgs/28/labels/1100" },
    { "href": "/orgs/28/labels/1098" },
    { "href": "/orgs/28/labels/1099" },
    { "href": "/orgs/28/labels/1101" }
  ],
  "sub_groups": []
}

Curl Command to Update Label Groups

In this example, the label group being updated with the request body from the code example above is identified by the its label group HREF.

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/draft/label_groups/3307b3d8-2ca2-48f5-877a-03ada95cd6de -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"labels":[{"href":"/orgs/28/labels/1100"},{"href":"/orgs/28/labels/1098"},{"href":"/orgs/28/labels/1099"},{"href":"/orgs/28/labels/1101"}],"sub_groups":[]}'

Curl Command to Delete a Label Group

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/draft/label_groups/3307b3d8-2ca2-48f5-877a-03ada95cd6de -u $KEY:$TOKEN

REST APIs 25.1 Developer Guide