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 group	`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 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 an Asynchronous GET Collection.

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]

Query Parameters for GET

Use the following required query parameters to restrict the results of the query when getting a collection of label groups.

Parameter	Description	Type	Required
`org_id`	Organization	Integer	Yes
`pversion`	Security Policy Version	String	Yes

`description`	The description of the label group to return. Partial matches are supported.	String	No
`external_data_reference`	A unique identifier within the external data source. For example, if label group information is stored in an external database.	String	No
`external_data_set`	The data source from which the resource originates. For example, if label group information is stored in an external database.	String	No
`key`	Key by which to filter	String	No
`max_results`	Maximum number of labels to return.	Integer	No
`name`	The specific name of a label group to return. Supports partial matches	String	No
`usage`	Include label usage flags	Boolean	No
`label_group_id`	Label Group UUID, for `[api_version][label_group_href]` and `[api_version][label_group_href]/member_of`	String	Yes

Response Properties

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`	User who originally created this label group "$ref": "../common/href_object.schema.json"
`updated_by`	User who last updated this label group "$ref": "../common/href_object.schema.json"
`deleted_by`	User 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`	Label Group is referenced by IP Forwarding Enabled Scopes	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/3307b3d8-2ca2-48f5-877a-03ada95cd6de",
    "created_at": "2015-07-25T00:58:31.046Z",
    "updated_at": "2015-07-25T00:58:31.046Z",
    "deleted_at": null,
    "created_by": {
      "href": "/users/3"
    },
    "updated_by": {
      "href": "/users/3"
    },
    "deleted_by": null,
    "name": "AppGroup",
    "description": null,
    "key": "app",
    "labels": [],
    "sub_groups": [
      {
        "href": "/orgs/2/sec_policy/draft/label_groups/9b30081e-e105-44d8-9945-4c8a30dbe849",
        "name": "AppGroup3"
      }
    ]
  },
  {
    "href": "/orgs/2/sec_policy/draft/label_groups/4c8e3325-c6dd-4dc2-aadc-971e9de270e4",
    "created_at": "2015-07-25T00:46:52.552Z",
    "updated_at": "2015-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"
      }
    ]
  },

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 does belong 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]

Request Body

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":[]}'

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]

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 API Developer Guide 22.2