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 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, explicitly designed for operations that produce errors. The Request-ID helps Illumio support troubleshooting 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. It 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 `POST`operation where an object was created
`204 No Content`	The 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. The error code 400 usually means that either the resource is not available (such as trying to update a previously deleted label), or there is a mistake in the URL (such as specifying /shlabels 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 be caused if more than one query parameter is used and the URI (including the query parameters) is not enclosed with single quotes 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 missing blank space between -u uname:’pswd’ and the next option, for example -H 'Accept: application/json'.

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

It can be caused by an incorrect curl command, for example, 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

It 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

It 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'?

REST APIs for 23.5