Skip to main content

REST APIs for 24.5

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