REST APIs for 23.5

Because virtual services are policy items, changes must be provisioned before they can affect your policy. Policy items always exist in either a draft (not provisioned) or active (provisioned) state.

Security policy items that must be provisioned to take effect include IP lists, rulesets, rules, services, virtual services, label groups, user groups, virtual servers, and PCE security settings.

For these items, the URL of the API call must include the URI element called :pversion, which can be set to either draft or active when you make the API call.

Depending on the method, the API follows these rules:

Use this method to get a collection of Virtual Services.

URI to Get a Collection of Virtual Services

GET [api_version][org_href]/sec_policy/:pversion/virtual_services

Curl Command

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

Response

Each individual virtual service returned is identified by the virtual service HREF. To GET, PUT, or DELETE an individual virtual service, identify the service by its HREF in the API call.

[
  {
    "href": "/orgs/7/sec_policy/draft/virtual_services/1828d8ff-aeb7-4735-9975-db692813d193",
    "created_at": "2017-10-29T19:41:15.648Z",
    "updated_at": "2017-10-29T19:41:15.648Z",
    "deleted_at": null,
    "created_by": {"href": "/users/14"},
    "updated_by": {"href": "/users/14"},
    "deleted_by": null,
    "update_type": null,
    "name": "Jawoo",
    "description": null,
    "service": { "href": "/orgs/7/sec_policy/draft/services/99" },
    "labels": [
      { "href": "/orgs/7/labels/88" },
      { "href": "/orgs/7/labels/82" },
      { "href": "/orgs/7/labels/92" },
      { "href": "/orgs/7/labels/101" }
    ],
    "ip_overrides": [
      "192.0.1.0",
      "192.168.100.0/24"
    ],
    "apply_to": "host_only"
  }
]

Use this method to get an individual virtual service. In the call, you identify the virtual service by its HREF, which can be obtained when you get a collection of virtual services.

Use the following query parameters to restrict the results of the query:

URI to Get an Individual Virtual Service

GET [api_version][virtual_service_href]

Curl Command

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

Response

{
    "href": "/orgs/2/sec_policy/draft/virtual_services/6005a35a-1598-4c7b-a827-be4390f46773",
    "created_at": "2017-12-11T20:56:28.629Z",
    "updated_at": "2017-12-11T21:07:10.407Z",
    "deleted_at": null,
    "created_by": { "href": "/users/9" },
    "updated_by": { "href": "/users/9" },
    "deleted_by": null,
    "update_type": "create",
    "name": "Docker1",
    "description": null,
    "service": { "href": "/orgs/2/sec_policy/draft/services/5" },
    "labels": [
      { "href": "/orgs/2/labels/18" },
      { "href": "/orgs/2/labels/26" },
      { "href": "/orgs/2/labels/126" }
    ],
    "ip_overrides": [
      "192.0.1.0",
      "192.168.100.0/24"
    ],
    "apply_to": "internal_bridge_network"
  }

Use this method to create an individual virtual service. Because a virtual service is a policy item, you must create it in the draft state and then provision the change using the Security Policy API.

Once the virtual service is provisioned, you can use the service binding method to bind the virtual service to a workload.

URI to Create an Individual Virtual Service

POST [api_version][org_href]/sec_policy/draft/virtual_services

Request Body

To create a virtual service, you need the HREF of the service you want to “bind” to a workload. You can obtain a service HREF by calling a GET collection with the service binding API.

Additionally, if you want to add labels to the virtual service, you need the HREF of each label you want to add. Label HREFs can be obtained by calling a GET collection with the labels API. Labels are represented in the JSON request body as an array, opened and closed by square brackets ([ ]).

{ 
  "name": "MyVirtualService", 
  "description": "Test",
  "service": { "href": "/orgs/7/sec_policy/draft/services/218" }, 
  "labels": [ 
    { "href": "/orgs/7/labels/88" }, 
    { "href": "/orgs/7/labels/82" }, 
    { "href": "/orgs/7/labels/92" }, 
    { "href": "/orgs/7/labels/95" } 
  ] 
}

Curl Command

To create a new virtual service:

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/2/virtual_services -H "Content-Type: application/json" -u $KEY:$TOKEN.-d '{ "name": "MyVirtualService", "description": "Test", "service": {"href": "/orgs/7/sec_policy/draft/services/218"}, "labels": [{"href": "/orgs/7/labels/88"}, {"href": "/orgs/7/labels/82"}, {"href": "/orgs/7/labels/92"}, {"href": "/orgs/7/labels/95" }]}' 

This method enables you to create a collection of virtual services in your organization using a single API call instead of creating individual services one at a time.

This capability is useful if you want to keep a set of PCE resources in sync with your internal representation of the resources, such as a configuration management database (CMDB) that holds the “source of truth” for your PCE resources.

After virtual services are created and the identifiers added to the service properties, you can get a collection of virtual services using query parameters that include the external data reference. You can also run an asynchronous query to get all virtual services through an offline job, which includes the external data references in the response.

The two properties you can use when creating virtual services, external_data_set and external_data_reference are UTF-8 strings with a maximum length of 255 characters. The contents must form a unique composite key, meaning that both values of these properties are treated as a unique key. These two properties together are recognized as a unique key, even if one of them is left blank or set to zero.

URI to Create a Collection of Virtual Services

PUT [api_version][org_href]/sec_policy/draft/virtual_services/bulk_create

URI to Update a Collection of Virtual Services

PUT [api_version][org_href]/sec_policy/draft/virtual_services/bulk_update

Request Body

To create a collection of virtual services, pass a JSON object that describes the details of the virtual service. This method's request body and curl command follow the same structure used to create an individual virtual service; you only add multiple virtual service JSON objects instead of just one.

Additionally, the href field must be present in the body for each virtual service you update in the bulk_update.

To update (PUT) an individual virtual service, you need to know the HREF of the virtual service you want to update. Virtual service HREFs are returned when you get a collection of virtual services.

URI to Update an Individual Virtual Service

PUT [api_version][org_href]/sec_policy/draft/virtual_services/virtual_service_id

Request Properties

The request properties for updating a virtual service are the same as those for creating a virtual service.

Request Body

This example request body can be passed to update a virtual service to include a workload binding:

{
  "service": { "href": "/orgs/2/sec_policy/draft/services/91" },
  "labels": [ 
    { "href": "/orgs/2/labels/316" },
    { "href": "/orgs/2/labels/101" },
    { "href": "/orgs/2/labels/102" },
    { "href": "/orgs/2/labels/103" }
  ]
}

Curl Command

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/draft/virtual_services/256525b6-e7c5-4ad7-b7af-e70586aa1078 -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"name":"test","description":null,"service":{"href":"/orgs/2/labels/316"},"labels": [{"href":"/orgs/2/labels/101"}, {"href":"/orgs/2/labels/102"}, {"href":"/orgs/2/labels/103"}]}' 

This method creates one or more service bindings, which associate (or “bind”) a virtual service to a workload. When you call this method, you specify the virtual service and workload you want to bind, plus you can optionally specify port overrides to use a different port for the service.

The JSON request body for creating a service binding is an array, which allows you to create multiple service bindings with a single POST.

Before you create a service binding, make sure that the virtual service you want to bind to a workload has been published and is in the active policy state.

URI to Create a Service Binding

POST [api_version][org_href]/service_bindings

Request Parameters

The request body for creating a service binding is an array of service binding objects. Because this JSON request body is an array, you can create multiple service bindings in a single POST.

This is an example JSON representation of a single service binding:

[{"workload": {"href": "/orgs/1/workloads/45c69cf3-4cbb-4c96-81ee-70e94baea1b8"}, "virtual_service": {"href": "/orgs/1/sec_policy/draft/virtual_services/a735332e-5d31-4899-a3a5-fac7055e05c0"}, "port_overrides": [{"port": 14000, "protocol": 6, "new_port": 26000 }]}]

Curl Command

To create a single service binding:

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/2/service_bindings -H "Content-Type:application/json" -u $KEY:$TOKEN -d '[{"workload":{"href":"/orgs/1/workloads/45c69cf3-4cbb-4c96-81ee-70e94baea1b8"}, "virtual_service":{"href":"/orgs/1/sec_policy/draft/virtual_services/a735332e-5d31-4899-a3a5-fac7055e05c0"}, "port_overrides":[{"port":14000,"protocol":6,"new_port":26000}]}]' 

Request Body to Create Multiple Service Bindings

An example JSON request body for creating multiple service bindings with a different port number:

[{"workload": {"href": "/orgs/1/workloads/820efcdc-c906-46b9-9729-26bab7a53223"}, "virtual_service": {"href": "/orgs/1/sec_policy/draft/virtual_services/e38ce044-d2ac-4d7f-aeec-16ef8fbd0b15"}, "port_overrides": [ {"port": 10000, "protocol": 6, "new_port": 26000 } ]}, {"workload": {"href": "/orgs/1/workloads/820efcdc-c906-46b9-9729-26bab7a53223"}, "virtual_service": {"href": "/orgs/1/sec_policy/draft/virtual_services/e38ce044-d2ac-4d7f-aeec-16ef8fbd0b15"}, "port_overrides": [ {"port": 11000, "protocol": 6, "new_port": 25000} ]}]

Service Binding Request Body

If you create more than one service binding with a single POST, all of the service bindings must be constructed properly or the POST will fail and no service bindings will be created.

For example, if you use POST to create 10 service bindings and one of the workloads referenced in the JSON payload uses an incorrect URI (HREF), the POST fails with an error message similar to the following message:

[ { "token": "invalid_uri", "message": "Invalid URI: {/orgs/1/workloadzzz/820efcdc-c906-46b9-9729-26bab7a53223}" } ]

You can use these methods to get one or more service bindings.

URI to Get a Collection of Service Bindings

GET [api_version][org_href]/service_bindings

URI to Get an Individual Service Binding

GET [api_version][service_binding_href]

Response Body

[ 
   {
     "href": "/orgs/7/service_bindings/287568ad-4a1f-4000-a9fb-e67d1dabce15", 
     "virtual_service": {"href": "/orgs/7/sec_policy/active/virtual_services/256525b6-e7c5-4ad7-b7af-e70586aa1078"}, 
     "workload": {"href": "/orgs/7/workloads/baef2547-2036-4e00-b6f7-3f4be1f7669a", 
     "name": null, 
     "hostname": "AssetMgt-proc2", 
     "deleted": false }, 
     "port_overrides": [{"new_port": 8080,"protocol": 6,"port": 3306}]
     }, 
        {
           "href": "/orgs/7/service_bindings/faebe7bf-0bb7-49a5-868e-8297e038fa9e", 
           "virtual_service": {"href": "/orgs/7/sec_policy/active/virtual_services/7b46fce0-4933-4e29-b86c-7a2a71e686ed"}, 
           "workload": {"href": "/orgs/7/workloads/aee4381b-9836-45b6-b7ab-aee246bf482f", 
           "name": null, 
           "hostname": "onlinestore-web2", 
           "deleted": false }, 
           "port_overrides": [] 
         },
         {
           "href": "/orgs/7/service_bindings/924ad8c2-94bf-40f5-bc4c-13474982bd00", 
           "virtual_service": {"href": "/orgs/7/sec_policy/active/virtual_services/256525b6-e7c5-4ad7-b7af-e70586aa1078"}, 
           "workload": {"href": "/orgs/7/workloads/69fd736b-cd21-4a4c-bdb9-132207c760ce", 
           "name": null, 
           "hostname": "test-us", 
           ": false }, 
           "port_overrides": [] 
         }
]

Curl Command to Get an Individual Service Binding

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/service_bindings/xxxxxxxx-4a86-4dd4-b303-23f699d0ebbf -H "Accept: application/json" -u $KEY:$TOKEN

Curl Command to Get Service Binding Collection

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

To delete both the service bindings and virtual services, delete the service bindings first, then delete the virtual services.

URI to Delete an Individual Service Binding

DELETE [api_version][service_binding_href]

Curl Command to Delete a Service Binding

Use this curl command to delete the service binding:

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/service_bindings/xxxxxxxx-4a86-4dd4-b303-23f699d0ebbf -u $KEY:$TOKEN