API payload and XML tags

The firewall API uses XML payloads to send and receive data.

API payload

The firewall uses the HTTP POST method for configuration requests rather than the standard GET, POST, PUT, and DELETE methods. It uses custom XML tags within the payload for specific operations.

For example, when you create a new object in the firewall, make sure the request body includes the <Set> tag to specify the object's attributes and values. The firewall accepts only these custom tags, which are transmitted using the HTTP POST method.

You must send the payload using the following URL:

https://<Firewall IP address>:<port>/webconsole/APIController

For IP address, you can use the web admin console's IP address or hostname. The port is the Admin console HTTPS port you configured on Administration > Admin settings.

XML tags

The firewall uses the following custom tags:

• <Request>: Use this tag to send a request to the API. The API version is optional and requires version-specific syntax.

• <Login>: Use this tag to authenticate API requests with the firewall.

  Example

  <Request APIVersion="1905.2">
      <Login>
          <Username>username</Username>
          <Password>password</Password>
      </Login>
  </Request>
  

• <Set operation="add"> or <Set operation="update">: Use the Set tag to perform add or update operations.

  • Use the "add" operation to create new objects, rules, and policies.

  • Use the "update" operation to change settings that you can't add, such as SSL/TLS inspection settings. You can only update these settings.

  If you don't specify the "operation" tag, the firewall considers it an add request. If the object doesn't support the add functionality, for example, SSL/TLS inspection settings, the request doesn't succeed.

  Example

  <Request>
      <Login>
          <Username>username</Username>
          <Password>password</Password>
      </Login>
      <Set operation="add">
          <IPHost>
              <Name>IPaddress</Name>
              <IPFamily>IPv4</IPFamily>
              <HostType>IP</HostType>
              <IPAddress>1.1.1.1</IPAddress>
          </IPHost>
      </Set>
  </Request>
  

• <Get>: Use this tag to get data from the firewall.

  Example

  <Request>
      <Login>
          <Username>username</Username>
          <Password>password</Password>
      </Login>
      <Get>
          <IPHost></IPHost>
      </Get>
  </Request>
  

• <Remove>: Use this tag to delete data from the firewall. You can't delete settings, such as SSL/TLS inspection settings. You can only update these settings.

  Example

  <Request>
      <Login>
      <Username>username</Username>
      <Password>password</Password>
      </Login>
      <Remove>
          <IPHost>
              <Name>CustomName</Name>
          </IPHost>
      </Remove>
  </Request>
  

• <Filter>: Use this tag to get data from the firewall based on certain criteria, for example, the object name. Specify the criteria using the <key> tag and the attribute values for "name" and "criteria".

  Supported criteria: [=,!=,like]

  Example

  Request>
      <Login>
          <Username>username</Username>
          <Password>password</Password>
      </Login>
      <Get>
          <IPHost>
              <Filter>
                  <key name="Name" criteria="like">Name of IP Host</key>
              </Filter>
          </IPHost>
      </Get>
  </Request>
  

• <Response>: This tag contains the response to your API request.

• <Status>: This tag is part of the <Response> tag and shows the status of your API request.

• transactionid: This attribute ensures the integrity of the request and response transaction. It's an optional attribute used in the <Set> tag. If you use it, we recommend using an alphanumeric value.

  Example

  <Request>
      <Login>
          <Username>username</Username>
          <Password>password</Password>
      </Login>
      <Set transactionid="xyz123">
          <IPHost>
              <Name>IPaddress</Name>
              <IPFamily>IPv4</IPFamily>
              <HostType>IP</HostType>
              <IPAddress>1.1.1.1</IPAddress>
          </IPHost>
      </Set>
  </Request>
  

API help

The API help shows the tags, attributes, and status codes used in the firewall. See API help.

To know how to format the XML requests, see Sample configuration for each menu in the API help.

Each module's left menu and attributes are similar to the web admin console settings. For more details about an attribute, see the corresponding help page.

Troubleshooting API requests