Skip to main content

REST APIs for 22.2

REST API URIs

This section describes the URI syntax used with this API, which can be different depending on the REST call you are making and the types of Illumio resources on which you are operating.

API Version and Org HREF

The API version and organization HREF are two variables used in every call made to this API.

The current version of the Illumio Core REST API is version 2 (v2), which is represented in method URIs by the [api_version] variable. Version 1 (v1) is still supported.

Note

The parameter tables and code examples in this document typically describe the v1 APIs, which in many cases are the same or very similar to the v2 APIs. For v2 API parameter tables, code examples, and authorization permissions, see the Illumio Core REST API Reference.

You can determine the organization HREF for the PCE when you use the login API to authenticate with the PCE and obtain a session token. In method URIs, this value is represented by the [org_href] variable.

In response to using the login API, the organization HREF is listed as shown, but depends on the version of the API you are using:

"orgs": [
    {
       "org_id": 2,
       "org_href": "/orgs/2",

Note that both [api_version] and [org_href] begin with a forward slash:

  • [api_version] - /api/v2

  • [org_href] - /orgs/2

For example, to get a collection of labels that exist inside an organization, construct the URI as follows, with the API version and the organization HREF shown in blue font:

GET [api_version][org_href]/labels

To get all of the API keys created by a specific user, construct the URI as follows, with the HREF path to the user shown in a blue font:

GET api/v2/orgs/1/api_keys
Port Number

The port number used in the code examples is 8443, which is the default. However, since the port number might be different depending on the implementation, ask your Illumio system administrator which port number to use when making calls to the Illumio Core REST API.

GET Collections URI Syntax

The base URI for Illumio REST API endpoint for GET collections:

GET http://[pce_hostname]:[port][api_version][org_href]/[api_endpoint]

Important

When making API calls, the [pce_hostname] or [pce_hostname]:[port] should not end with a forward slash ('/'). This is because [api_version] begins with a forward slash.

For example, the URI for getting a collection of workloads uses this syntax:

GET https://pce.my-company.com:8443/api/v2/orgs/1/workloads

In the rulesets API, you also have the ability to get all of the rules ("sec_rules") contained in a ruleset. The URI syntax for this operation is as follows:

GET http://[pce_hostname]:[port][api_version][object_href][api_endpoint]

For example:

GET [api_version][ruleset_href]/sec_rules
Non-GET Collections URI Syntax

For the non-GET methods of PUT, POST, and DELETE, the object HREF is listed as the endpoint, as shown here:

PUT [api_version][object_href]

The relative path of the [api_version] ("api/v2/") indicates that version 2 of the API is in use.

In the URI above, [org_href] is not added because it is included in the [object_href] string. For example, this is the [object_href] for a workload:

/orgs/2/workloads/3e3e17ce-XXXX-42b4-XXXX-1d4d3328b342

Another case is performing PUT, POST, or DELETE operations on the rules contained in a ruleset. The URI syntax is the same as a GET operation.

Security Policy Items and “:pversion”

The URI for security policy items is as follows:

[pce_host][port][api_version][org_href]/sec_policy/draft/[api_endpoint]
See also: