Request Calls Using Curl
This section explains how to use curl commands to work with Illumio APIs by defining some standard options and constants.
Curl Overview
Curl is a common command-line data transfer tool for making API calls and is especially useful in scripts written for automated tasks.
The syntax for using curl with the API for logging a user into the PCE is as follows:
curl -i -X <HTTP method> <uri_of_api> <header> -u $KEY:$TOKEN -Options
The syntax for using curl with the API for PUT operations using an API key for authentication is as follows:
curl -i -X PUT <URI of API> -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{ "json_property": "property_value", "json_property": "property_value" }' For example:
curl -i -X PUT https://scp.illum.io:8443/api/v2/users/11/local_profile/password -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{ "current_password": "NotMyReal_Old*96Password", "new_password": "NotMy*76New!pswd" }' Curl-specific Options
For the curl examples provided in this API documentation, a few standard curl options are defined as follows.
The user and password to use for server authentication:
-u/--user <user:password>
For brevity, code examples typically use constants for -u username:'password' arguments. $TOKEN represents an authentication token (a string enclosed by single quotes to prevent it from unintentionally expanding):
-u $KEY:$TOKEN
(HTTP) Header to use when getting a web page:
-H/--header <header>
(HTTP) Specify an HTTP method to use when communicating with the HTTP server:
-X/--request <command>
Example:
-X POST
(HTTP) Send the specified data in a POST request to the HTTP server in a way that emulates a user filling in an HTML form and clicking Submit:
-d/--data <data>
Example API Call Using CURL
To get all of the API keys of a specific user using the user's session credentials:
curl -i -X GET https://scp.illum.io:8443/api/v2/users/11/api_keys -H "Accept: application/json" -u $KEY:$TOKEN
Using Curl with json-query
When using json-query to format the output of curl commands, be aware that due to a json-query bug, this does not work with the curl -i option, which displays response headers. When you use the curl -i option, such as to see the total number of workloads when using GET workloads, you might get various error messages like curl: (3) Illegal port number. To work around this issue, remove the -i option and retry the curl command.