Web API basics

You can use the web API commands, with the command-line, to automate configuration using scripts instead of using the user interface.

This section uses examples of the cURL command line tool for transferring data with URL syntax. Each command is designed to work without user interaction. The cURL executable is free and open software that runs under a wide variety of operating systems.

Each cURL example includes standard parameters followed by the actual web API URL that executes a command on your ePO server. These parameters should help you to understand what the command does, although in practice you should implement tighter security when it comes to trusting the site's certificate.

Note

The web API supports using other command-line tools, for example wget (part of the GNU Project, © 2009, Free Software Foundation, Inc.), to retrieve data from your ePO server.

This command, for example, shows the cURL syntax and the URL to illustrate the core capabilities of the web API.

> curl -k -u ga:ga https://localhost:8443/remote/core.help

This table shows the parameters used with the curl command example.

In the examples in this document, the ePO server and destination port are identified as "localhost" and "8443" (the default). You need to replace these entries with the server name and port number of your own installation.

Note

Web API commands follow all role-based permissions as enforced through the ePO server graphical interface.

The web API is used primarily for two purposes:

Scripts using the web API can be run from any computer that can connect to the ePO server. For security reasons, these commands should not be run on the same computer as the ePO server itself.

General syntax

The general syntax for a command sent via HTTPS is:

https://<server>:<port>/remote/<command>?<arg1>=<val1>&<arg2>=<val2>

Additional arguments can be specified as needed.

Some commands require input in other formats, such as importing a file. For example, importing an XML file containing permission sets looks like this:

> curl -k -u ga:ga "https://localhost:8443/remote/core.importPermissionSets" -F file=@permissionSets.xml

Output options

By default, commands return output in a human-readable format. When scripting, however, you usually want commands to return data in a more machine-readable format. This format is controlled with the :output parameter.

https://localhost:8443/remote/core.help?:output=json

This example returns data in JavaScript Object Notation (JSON) format. Other options include verbose (default), terse, and xml. These arguments must be supplied as all lowercase text. In addition, the parameters shown in this table are available.