This page contains the information on the XML tags and the status codes used in the API. XML tags are used for applying the configurations on the appliance. When XML response is received, it contains a status code with the description about the success/failure of the operation.

Please find below the list of XML tags and the status code with their descriptions:

List of tags used in API
  1. Tag Name: <Request>
    2. Description: It is used for sending XML Request. To apply any configuration this tag is necessary. API Version also needs to be specified for configurations to be applied successfully.
    Usage:
    Attribute - APIVersion
    Attribute Value - Version of API used. For example: "1900.2"
    Example:
    <Request APIVersion="1900.2">
        <Login>
            <Username>admin</Username>
            <Password >adminpassword</Password>
        </Login>
    </Request>

  2. Tag Name: <Login>
    3. Description: It is used for Authentication.
    Usage:
    Attribute - N/A
    Attribute Value - N/A
    Example:
    Please refer the above example.

  3. Tag Name: <Username>
    4. Description: Specify the username in this tag.
    Usage:
    Attribute - N/A
    Attribute Value - N/A
    Example:
    Please refer the above example.

  4. Tag Name: <Password>
    5. Description: Specify the password in this tag.
    Usage:
    Attribute - N/A
    Attribute Value - N/A
    Example:
    Please refer the above example.

  5. Tag Name: <Set>
    6. Description: It is used to inform that the request is to be served as Add/Update depending on the Attribute value.
    Note: If, no "operation" attribute/value is defined in the tag, then Add operation will be performed followed by Update
    Usage:
    Attribute - operation
    Attribute Value - Add/Update
    Example:
    <Request>
        <Login>
            <Username>admin</Username>
            <Password>adminpassword</Password>
        </Login>
        <Set operation="add">
            <IPHost>
                <Name>CustomIPHostTypeIPV4</Name>
                <IPFamily>IPv4</IPFamily>
                <HostType>IP</HostType>
                <IPAddress>1.1.1.1</IPAddress>
            </IPHost>
        </Set>
    </Request>

    Additional inputs to set sensitive information:
        i) Parameter: SecureStorageMasterKey
        Description:Enter the secure storage master key. It's the master key for the firewall from which you've exported the configuration. If you don't enter the master key, your firewall won't import sensitive information, such as passwords, and the dependent settings.
        If you don't have the master key, ask the default administrator (username: admin).
        Example:
        https://1.1.1.1:4444/webconsole/APIController?SecureStorageMasterKey=Passw0rd@12345&reqxml=<Request> ....</Request>

        ii) Attribute: Token
        Description:Enter the token. You receive it in the GET request. The firewall imports and decrypts sensitive information using the secure storage master key and the token.
        Example:
    <Request Token="$sfos$0$N=4000CAnkyXQo7T7e6LnNgrcZJFx0Vg7Z7tyrglkqo1KosvB6VRTmHqDyA05yTlkVkmWTbzABokmciI048Tnv4y9j3OiEEWi1E_HklZI5A2qq5v8JL1AlZfykgnnjylc6FT5feV">
        <Login>
            <Username>admin</Username>
            <Password>admin</Password>
        </Login>
        <Set operation="update">
            <BackupRestore>
                <ScheduleBackup>
                    <BackupMode>Local</BackupMode>
                    <BackupPrefix>back_up_test</BackupPrefix>
                    <BackupFrequency>Never</BackupFrequency>
                      .
                      .
                    <EncryptionPassword hashform="mode1">$sfos$7$0$7B68U8kfUxfQtMZ eCl7TO5YFSGes0UDTgRqWg5EXCwMpTXaVcRqqjIe5F4yH~</EncryptionPassword>
                </ScheduleBackup>
            </BackupRestore>
        </Set>
    </Request>

  6. Tag Name: <Get>
    7. Description: It is used to inform that the request needs to be served for retrieving data of the entity specified.
    Usage:
    Attribute - N/A
    Attribute Value - N/A
    Example:
    <Request>
        <Login>
            <Username>admin</Username>
            <Password>adminpassword</Password>
        </Login>
        <Get>
            <IPHost></IPHost>
        </Get>
    </Request>

  7. Tag Name: <Filter>
    8. Description: It is used for retrieving entity data based on the criteria specified in the <Key> tag. It is only applicable for entity "Name"
    Usage:
    Attribute - N/A
    Attribute Value - N/A
    Example:
    <Request>
        <Login>
            <Username>admin</Username>
            <Password>adminpassword</Password>
        </Login>
        <Get>
            <IPHost>
                <Filter>
                    <key name="Name" criteria="like">CustomIPHostTypeIPV4</key>
                </Filter>
            </IPHost>
        </Get>
    </Request>

  8. Tag Name: <Key>
    9. Description: It is used within the <Filter> tag to specify the filter key and Filter criteria.
    Usage:
    Attribute - name, criteria
    Attribute Value - name = "Name", criteria = ["=","!=","like"]
    Example:
    Please refer the above example.

  9. Tag Name: <Remove>
    10. Description: It is used to delete data.
    Usage:
    Attribute - N/A
    Attribute Value - N/A
    Example:
    <Request>
        <Login>
            <Username>admin</Username>
            <Password>adminpassword</Password>
        </Login>
        <Remove>
            <IPHost>
                <Name>CustomIPHostTypeIPV4</Name>
            </IPHost>
        </Remove>
    </Request>

  10. Tag Name: <Response>
    11. Description: Response of any request will be displayed in this tag.
    Usage:
    Attribute - APIVersion
    Attribute Value - Same value as specified in the XML Request or if it is not specified then active firmware API Version will be considered.
    Example:
    <Response APIVersion="1900.2">
        <Login>
            <status>Authetication Successful</status>
        </Login>
        <IPHost transactionid="">
            <Status code="502">Message.IPHostRecordExists</Status>
        </IPHost>
    </Response>

  11. Tag Name: <Status>
    12. Description: It is a part of the <Response> tag and it indicates the configuration status based on the code.
    Usage:
    Attribute - code
    Attribute Value - code value.
    Example:
    <Response APIVersion="1900.2">
        <Login>
            <status>Authetication Successful</status>
        </Login>
        <IPHost transactionid="">
            <Status code="502">Operation failed. Entity having same name already exists</Status>
        </IPHost>
    </Response>

  12. Tag Name: <Password hashform="mode1">xxx</Password>
    13. Description: Enter the encrypted password. You receive it in the GET request. Alternatively, enter the unencrypted password.

How to use API ?
Please use the below link to use API:
https://<Firewall IP>:<port>/webconsole/APIController?reqxml=<Add the XML request here>
Note: Port you mention in above URL should be same as the port you have configured as Admin Console HTTPS Port from System > Administration > Settings.
Example:
  1. Set Request
    2. https://<Firewall IP>:<port>/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password>adminpassword</Password></Login><Set> <IPHost transactionid=""><Name>ip2</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType><IPAddress>2.2.2.9</IPAddress></IPHost> </Set></Request>

  2. Set request to send sensitive information
    3. https://<Firewall IP>:<port>/webconsole/APIController?SecureStorageMasterKey=Passw0rd@12345&reqxml=<Request Token="token"><Login><Username>admin</Username><Password>admin</Password></Login><Set> <backuprestore transactionid=""><schedulebackup><backupmode>Local</backupmode><backupprefix>back_up_test</backupprefix><ftppath/><username/><ftpserver/><password/><emailaddress/><backupfrequency>Never</backupfrequency><day/><hour/><minute/><date/><encryptionpassword hashform="mode1">EncryptedPassword</encryptionpassword></schedulebackup></backuprestore></Set></Request>

  3. Get Request
    4. https://<Firewall IP>:<port>/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password>adminpassword</Password></Login><Get> <IPHost></IPHost> </Get></Request>

Status Code and Description
Status Message
200 Configuration applied successfully.
201 Operation partially successful.
203 Operation successful but few configurations could not be applied. Please contact Support.
204 - 210 Operation partially failed.
211 - 215 Warning messages will be displayed. For more information, refer to the section "Status Message Information" on each page.
216 Operation Successful. For more information, refer to the section "Status Message Information" on each page.
500 Operation could not be performed on Entity.
501 Configuration parameters validation failed.
502 Operation failed. Entity having same name already exists.
503 Operation failed. Entity having same parameter details already exists.
504 - 510 Operation failed. Deleting entity referred by another entity.
511 - 520 Operation failed. Please contact Support.
521 XML Request not compatible with current API version.
522 - 525 Maximum limit reached for entity.
526 Record does not exist.
528 Trying to update default entities which are not editable.
529 Invalid XML request for entity/entities.
530 API Version not supported for specific entity.
541 - 590 Operation failed. For more information, refer to the section "Status Message Information" on each page.
599 Not having privilege to add/modify configuration.

© Copyright 2019 Limited. All rights reserved.
is registered trademarks of Limited and Group. All other product and company names mentioned are trademarks or registered trademarks of their respective owners.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording or otherwise unless you are either a valid licensee where the documentation can be reproduced in accordance with the license terms or you otherwise have the prior permission in writing of the copyright owner.