Tips & Tricks: API configuration

You can do a lot of cool things with the API. One of the more common tasks an administrator can perform is accessing, updating and changing the firewall's configuration through some creative scripting while leveraging the ease of use of the API.

Just like the GUI and the CLI, accessing the API requires authentication. An authentication token can be generated with the below command using each administrator's own username and password. We don't recommend sharing this token.

https://<hostname>/api/?type=keygen&user=<username>&password=<password>

The resulting token can then be injected in any API command as an authentication token like so:

/api/?type=config&action=get&key=<key>&xpath=/config

The above command will return the entire configuration file, but you can also filter the xpath down to a smaller, more specific subset of the configuration:

/api/?type=config&action=get&xpath=/config/devices
/api/?type=config&action=get&xpath=/config/mgt-config
/api/?type=config&action=get&xpath=/config/predefined
/api/?type=config&action=get&xpath=/config/shared

If you look at the configuration XML, the xpath will make more sense:

You can use the API browse function to look through all the possible xpath options, so you can build a more narrow filter to suit your needs:

/php/rest/browse.php/config

To add new objects, use the 'set' action or 'delete' to remove an object or 'edit' to change an object:

/api/?type=config&action=set&key=<key>&xpath=/config/devices/entry/vsys/entry/address&element=<entry name='test'><description>my desc</description><ip-netmask>1.1.1.1</ip-netmask></entry>

/api/?type=config&action=delete&key=<key>&xpath=/config/devices/entry/vsys/entry/address&element=<entry name='test'></entry>

As you see, when you start performing rather simple operations, the URL starts to become pretty complex quickly. Another cool way to figure out which xpaths to use for certain operations is by using the CLI debug mode:

> debug cli on
(leaf-tag: cli value: on)
((eol-matched: . #t) (cli-handler: . debug-cli-handler) (context-inserted-at-end-p: . #f))

> configure 
()
((context-inserted-at-end-p: . #t))
Entering configuration mode
[edit] 

# set address "test55" description "API object" ip-netmask 10.0.0.1
(container-tag: address container-tag: entry key-tag: name value: test55 leaf-tag: description value: API object leaf-tag: ip-netmask value: 10.0.0.1)
((eol-matched: . #t) (xpath-prefix: . /config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1']) (context-inserted-at-end-p: . #f))
(address (entry (@ (name test55)) (description API object) (ip-netmask 10.0.0.1)))
(entry (@ (name test55)) (description API object) (ip-netmask 10.0.0.1))

                             This is the XPath in the set command above
<request cmd="set" obj="/config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1']/address/entry[@name='test55']" cookie="1285104864936584">
<description>API object</description><ip-netmask>10.0.0.1</ip-netmask></request>
           This is the element in the set command above

2016-02-16 16:38:32
<response status="success" code="20"><msg>command succeeded</msg></response>

[edit]            
# 

If the system is multivsys, the xml will need to be adjusted to reflect the proper vsys, so the xpath becomes:

/config/devices/entry[@name=’localhost.localdomain’]/vsys/entry[@name=’vsys1’]/

If you're not scared yet, please go visit our API discussion forum where you'll find a lot of interesting subjects being discussed on real-world use cases and nifty ways to automate operations using python or perl.

Please leave a comment or a like if you've found this information helpful.

Thanks!

Tom