Skip to main content

REST APIs for 24.2.20 and 24.2.10

HTTP Requests and Responses

This section explains how to formulate HTTP requests and read HTTP responses.

HTTP Request Headers

Set an Accept: application/json header on all GET operations (optional for DELETE operations):

-H 'Accept: application/json'

Set a Content-Type: application/json header on PUT and POST operations:

-H 'Content-Type: application/json'

HTTP Request Body

Most of the parameters and data accompanying requests are contained in the body of the HTTP request. The Illumio REST API accepts JSON in the HTTP request body. No other data format is currently supported.

PUT Operations

Illumio REST API PUT operations modify a subset of attribute-value pairs for a specified resource. The attributes that are not specified in the PUT operation are left unmodified.

For example, to update a user's phone number (using the Users API) without modifying the userʼs address, call PUT with a request that only modifies the phone number, and only the phone number is changed.

Response Header Request-ID

The Illumio REST API provides a useful troubleshooting feature that returns a unique Request-ID in the HTTP response header on calls made with this API.

You can provide the Request-ID when opening Illumio support tickets, which are designed specifically for operations that produce errors. The Request-ID helps Illumio support to troubleshoot specific operations and errors

If you are using curl to make REST API calls to the PCE, you can specify the curl -D flag plus a file name to write the response header to a file.

The following example shows a curl command to get a collection of workloads that uses the -D flag to write the response header to a file named temp_header.

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

The file contains the response header of the call (highlighted in blue bold font):

HTTP/1.1 200 OK
Server: nginx
Date: Wed, 09 Dec 2015 16:58:00 GMT
Content-Type: application/json
Content-Length: 2193032
Connection: keep-alive
Vary: Accept-Encoding
Vary: Accept-Encoding
Status: 200 OK
X-Total-Count: 1406
X-Matched-Count: 1406
ETag: "523d67cbd57b18d0e97bc8e7555142eb"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id:
9722c8b5-94dc-4a50-853a-8e8f22266528
Cache-Control: no-store
Pragma: no-cache

Response Types

The HTTP response includes:

  • An HTTP status code

  • A response body that contains data in JSON format:

    • Your requested data, if successful

    • An error code and message if there is an error

HTTP Status Codes — Success

The following table lists all expected success codes returned when you use the Illumio REST API:

HTTP Code

Description

200 OK

Successful operation where JSON body is returned.

201 Created

Successful POSToperation where an object was created.

204 No Content

Operation succeeded and nothing was returned.

HTTP Status Codes — Failure

All Illumio REST API methods (GET, POST, PUT, and DELETE) might fail with an error in the 400 range. Error code 400 usually means that the resource is unavailable (such as trying to update a previously deleted label) or that the URL contains a mistake (such as specifying /labels instead of /labels).

Other errors that might occur:

HTTP Code

Description

400 Bad Request

Something in the curl request was not correct, for example "curl -X -i GET" instead of "curl -i -X GET"

401 Authentication failure or HTTP/1.1 401 Unauthorized

For example, the user attempted to make an API call but forgot to log in, username or password were incorrect or missing, or a missing space before "-u"

403 Authorization failure

For example, the user is not authorized to make the call.

HTTP/1.1 403 Forbidden

For example, using the incorrect HTTP method (like using GET instead of POST), the incorrect org_id parameter was used

404 Invalid URL

HTTP/1.1 404 Not Found

For example, an incorrect API version number /api/v191/, missing or incorrect org_id, /orgs/{org_id}/, wrong URL, or a misspelled endpoint.

404 Page not found

For example, the wrong org_id in the URI or missing blank space before an option dash, like before -H 'Accept: application/json'

405 Method not allowed

For example, if you perform a POST on a resource that only allows PUT.

406 Invalid payload

The JSON request payload was constructed improperly.

Other Failure Codes
-bash: -H: command not found HTTP/1.1 401 Unauthorized

  • This can occur if more than one query parameter is used and the URI (including the query parameters) is not enclosed in single or double quotes.

    Example:

    'https://pce.my-company.com:8443/api/v2/orgs/2//workloads?managed=true&max_results=1'

curl: (3) Illegal port number

  • For example, a blank space is missing between -u uname:’pswd’ and the next option, -H 'Accept: application/json'.

parse error: Invalid numeric literal at line 1, column 9

  • It can be caused by an incorrect curl command, such as including a path parameter that isn't allowed, like using orgs/org_id for an endpoint that doesn't use it. This is also a known JSON query bug caused by using -i in a curl command that uses json-query. To see the headers returned from the curl command, remove json-query from the curl command and use -i, for example "curl -i -X GET ..."

curl: (23) Failed writing body

  • Can be caused by calling an endpoint that doesn't exist.

The property '#/' of type null did not match the following type: object in xxxxxxx.schema.json

  • Can be caused by a missing or incomplete request body.

[{"token":"input_validation_error","message":"Input validation failed. Details: {The property '#/' of type NilClass did not match the following type: object in schema xxxxx.schema.json}"}]

  • Is the wrong -H value being used? For example, is -H 'Accept: application/json' being used for a PUT or a POST instead of -H 'Content-Type: application/json'?

See also: