Using cURL

Use cURL to test the V‑Spark API from the command line. cURL is not required to use the V‑Spark API, but it can be a helpful tool, and is freely available for most operating systems.

Important: When using cURL to make API calls, it is important to remember that because URLs typically include the ? and & symbols to identify HTTP/HTTPS parameters, you must enclose the URL portion of your cURL command within quotation marks to prevent a Linux shell from intercepting and interpreting these characters.

Debugging cURL calls

These are some of the strategies Voci engineers use to debug cURL errors.

  1. Obtain verbose debugging information. Append --trace-asii $filename to your cURL command to log every interaction between cURL and the host to the file $filename. The contents of the saved file may help identify the problem.

  2. Add a timeout to the command. cURL requests don't timeout by default, and depending on network and host conditions, there may be a significant delay between your request and the host's response. To specify a timeout, append --max-time $seconds to your cURL command, where $seconds is the timeout threshold expressed in seconds.

  3. Add a conditional speed timeout. To timeout the request when its data transfer speed is slower than a certain threshold $speed for a certain amount of time $seconds, append --speed-limit $speed --speed-time $seconds to your command. Daniel Stenberg, cURL's maintainer, provides several useful example commands using this tag on his blog.

  4. Limit output to the response's HTTP code. Append -LI -w '%{http_code}' to your command to include only the response's HTTP code, then compare that code to your expected results.

Output readability

The JSON output that is produced by V‑Spark APIs is not easily readable by humans. When using cURL to make API calls, the output of the cURL command can be piped to Python in order to print that output in a more human-legible format, as in the following example:

$cURL_command | python -m json.tool

The json.tool module that is provided by Python sorts keys in JSON output alphabetically. To reformat JSON output without reorganizing key values, consider using the Python command jsonlint. This command includes JSON reformatting along with JSON validation and other capabilities, and is provided as part of the python-demjson-2.2.2-1.el7.noarch package on CentOS 7 systems.

Common cURL flags

These cURL tags are used frequently in examples. Refer to the cURL documentation for a full list.

-d

Identifies the data that you are sending to the HTTP server. File names must be preceded by an @ symbol. You can also use the - symbol after an @ symbol to indicate that the data to send to the HTTP server will be coming from standard input on your system, such as when a cURL POST command uses a pipe to receive data from another application.

-H

Identifies the type of content that you are sending ("Content-Type:application/json").

-I

Only returns the HTTP header, which is where the HTTP response code is located

-L

Tells cURL to follow the URL if it is marked as having been moved

-o

Tells cURL where to write the general output of the command. In this case, /dev/null, the Linux and macOS bit bucket is used. On Windows systems, you can write to a file named nul, for which Windows provides built-in device driver support.

-s

Causes cURL to run in silent mode. Ordinarily, cURL displays a progress meter as it executes.

-w

Specifies what cURL should write to standard output, and how to format that information. The string '%{http_code}' simply writes the contents of the variable http_code

-X

Identifies the request method to use when communicating with the target HTTP server. If no method is specified, the request defaults to GET.