API payload and XML tags

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

API payload

It doesn't use the GET, POST, PUT, and DELETE tags for configuration requests. Instead, it uses custom tags.

For example, to create a new object in the firewall, the XML payload requires a <Set> tag with the object's attributes and values. The custom tags are part of the request body and are sent using the HTTP POST method.

XML tags

The XML string must contain the API controller and the administrator sign-in and configuration requests. 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.