Using the /list API with cURL
The cURL utility makes it easy to test using the V‑Spark API by providing a command-line mechanism for invoking APIs such as the /list API. The next few sections provide examples of using the GET methods with the /list API from the command line via the cURL command.
The cURL utility is freely available for operating systems including Linux, Windows, and macOS. The command-line command for invoking the cURL utility is curl on Linux or Apple macOS systems. The executable command for invoking the cURL utility is curl.exe on Microsoft Windows systems.
Note
Escaped newlines (that is, lines in cURL commands or example output that end with a backslash) are added for readability. They must not be present in cURL commands, and are also not present in the output of those commands.
Example commands are shown in normal monospaced text. Example output from each command is shown in bold, monospaced text.
Tip
See Tips for Debugging and Managing cURL Calls for suggestions about how to debug and manage cURL calls.
This section discusses how to use the /list API to retrieve high-level configuration information from a specified V‑Spark installation. A sample cURL command to retrieve information about all of the organizations in a V‑Spark installation is the following:
curl -s $PROTOCOL://$HOST:$PORT/list/orgs?token=TOKEN
The variables in this command are the following:
- PROTOCOL
The protocol that your V‑Spark installation uses to communicate over the network, one of
httporhttps. V‑Spark installations use thehttpprotocol by default.- HOST
The host on which your V‑Spark installation is running, specified by host name or IPv4 IP address.
- PORT
The network port that the V‑Spark installation is listening on. The default is port 3000, which must still be specified in V‑Spark REST API calls.
- TOKEN
An authorization token that enables calls to the
/listAPI to access all data in a V‑Spark installation. If you are using cURL to access the API for information within a specific company, you can provide that company's authorization token to get the information that you need. If you are requesting higher-level information, you can always use the V‑Spark installation's root token to obtain the information that you are requesting. The root token for a default V‑Spark installation is located in the file/opt/voci/state/vspark/apitoken.
Note that no REST method has been specified in the preceding cURL command. That is because the cURL command defaults to performing a GET operation when no REST method is specified, and the /list API only supports the GET method.
As an example, the cURL command to use the HTTP protocol to retrieve configuration information for the organizations that have been defined in a V‑Spark installation on the host example.company.com is the following:
curl -s http://example.company.com/list/orgs?token=123456789012345678901234567890123
If you are using the root token to enable access to the V‑Spark configuration information, it is a 32-character string that is passed as an option using the token parameter.