Samples that use the REST management interface

You can submit REST management interface requests to manage the DataPower® Gateway.

Samples of how to use the REST management interface.

These examples show how to use curl to set up requests.
These examples show how to get management information.
These examples show how to work with domains.
These examples show how to work with objects.
These examples show how to work with directories and files.
- Create new directories and files with either POST or PUT requests
- List the files in a directory

Use the curl program to request a list of all active users on the DataPower Gateway

curl -k -u myID:myPW --request GET https://example.com:5554/mgmt/status/default/ActiveUsers

The response returns in a structured list.

{
  "_links": {
    "self": {
      "href": "/mgmt/status/default/ActiveUsers"
    },
    "doc": {
      "href": "/mgmt/docs/status/ActiveUsers"
    }
  },
  "ActiveUsers": [
    {
      "session": 199,
      "name": "user1",
      "connection": "web-gui",
      "address": "1.2.3.4",
      "login": "Wed Apr 15 14:58:39 2015", 
      "domain": "default"
    },
    {
      "session": 200,
      "name": "user1",
      "connection": "serial-port",
      "address": "1.2.3.4",
      "login": "Wed Apr 15 14:58:44 2015",
      "domain": "default"
    }
  ]
}

Use the curl program to request various kinds of time and day status for the DataPower Gateway

curl -k -u myID:myPW --request GET https://example.com:5554/mgmt/status/default/DateTimeStatus

The response has the following form.

{
  "_links": {
    "self": {
      "href": "/mgmt/status/default/DateTimeStatus"
    },
    "doc": {
      "href": "/mgmt/docs/status/DateTimeStatus"
    }
  },
  "DateTimeStatus": {
    "time": "Sun Sep 7 16:18:09 2014",
    "timezone": "EDT",
    "tzspec": "EST5EDT,M3.2.0/2:00,M11.1.0/2:00",
    "uptime2": "2 days 14:27:38",
    "bootuptime2": "133 days 01:01:34"
  }
}

Use a curl command to move the files between directories

Sending a curl command to move files between directories requires several steps.

Obtain the MoveFile schema from the actionqueue URI.

GET https://example.com:5554/mgmt/actionqueue/default/operations/MoveFile

Read the MoveFile action.

The store:///xml-mgmt.xsd schema is available for the XML management interface. This schema helps in the construction of REST management request payloads. The schema for the MoveFile operation provides a good point of comparison.

<xsdcomplexType name="ActionMoveFile">
  <xsdsequence>
    <xsd:element name="sURL" minOccurs="1" maxOccurs="1">
      <xsd:simpleType>
        <xsd:union memberTypes="tns:dmURL tns:dmEmptyElement" />
      </xsd:simpleType>
    </xsd:element>
    <xsd:element name="dURL" minOccurs="1" maxOccurs="1">
      <xsd:simpleType>
        <xsd:union memberTypes="tns:dmURL tns:dmEmptyElement" />
      </xsd:simpleType>
    </xsd:element>
    <xsd:element name="Overwrite" minOccurs="0" maxOccurs="1">
      <xsd:simpleType>
        <xsd:union memberTypes="tns:dmToggle tns:dmEmptyElement" />
      </xsd:simpleType>
    </xsd:element>
  </xsd:sequence>
</xsd:complexType>

Run a curl command to move a file from a source directory (sURL) to a destination directory (dURL). Submit a POST request to the actionqueue resource of the default domain .

POST https://example.com:5554/mgmt/actionqueue/default
{
  "MoveFile": {
    "sURL": "temporary:///testing_myfile.xml",
    "dURL": "local:///testing_myfile.xml"
  }
}

Because the REST interface implements synchronous action execution only, the client immediately receives an HTTP 200 OK response code. Otherwise, the client receives a response that contains an error message that describes the failure.

200 OK
{
  "_links": {
    "self": {
      "href": "/mgmt/actionqueue/default"
    },
    "doc": {
      "href": "/mgmt/docs/actionqueue/operations/MoveFile"
    }
  },
  "MoveFile": {
    "status": "Operation completed."
  }
}

For example, a possible error response from a POST request for a file testing_myfile.xml that does not exist in a domain test-domain_1. The JSON_file payload file specifies the source and target, where sURL is the location of the source file and dURL is the location of the target file.

curl -k -u myID:myPW --request POST https://example.com:5554/mgmt/actionqueue/test-domain_1 -d JSON_file
{
  "MoveFile": {
   "sURL": "local:///testing_myfile.xml",
   "dURL": "temporary:///testing_myfile.xml"
  }
}

The response has a response that indicates the error.

{
  "MoveFile": {
    "_links": {
      "self": {
        "href": "/mgmt/actionqueue/test-domain_1"
       },
      "doc": {
        "href": "/mgmt/docs/actionqueue/operations/MoveFile"
      }
    },
    "error": [
        "local:///testing_myfile.xml - No such file or directory",
        "move local:///testing_myfile.xml temporary:///testing_myfile.xml"
    ],
    "MoveFile": "Operation has failed, please review error log."
  }
}

Get the status root

The status root lists the class names that you use to request status providers. The links are presented directly on the REST API root URI GET response in the first example. This list indicates the correct formatting of the status providers.

GET https://example.com:5554/mgmt/status/

The response returns a structured list. In the response, {domain} is the variable that represents the domain name.

{
  "_links": {
    "self": {
      "href": "/mgmt/status/"
    },
    "ActiveUsers": {
      "href": "/mgmt/status/{domain}/ActiveUsers"
    },
    "Battery": {
      "href": "/mgmt/status/{domain}/Battery"
    },
    "ConnectionsAccepted": {
      "href": "/mgmt/status/{domain}/ConnectionsAccepted"
    },
    "CPUUsage": {
      "href": "/mgmt/status/{domain}/CPUUsage"
    },
    "CryptoEngineStatus2": {
      "href": "/mgmt/status/{domain}/CryptoEngineStatus2"
    },
    "CryptoHwDisableStatus": {
      "href": "/mgmt/status/{domain}/CryptoHwDisableStatus"
    },
    "CryptoModeStatus": {
       "href": "/mgmt/status/{domain}/CryptoModeStatus"
    },
    ...
  }
}

List the supported actions at the `actionqueue` operations URI

Use a GET request to identify the valid actions and their name formats. The domain parameter specifies the domain name that you are targeting. In the response, {domain} is the variable that represents the domain name.

GET https://example.com:5554/mgmt/actionqueue/default/operations
{
    "_links": {
       "self": {
          "href": "/mgmt/actionqueue/default/operations"
       },
       "AddKnownHost": {
          "schema": {
             "href": "/mgmt/actionqueue/{domain}/operations/AddKnownHost"
          },
          "metadata": {
             "href": "/mgmt/metadata/{domain}/operations/AddKnownHost"
          }
       },
       ...
    },
}

Recursively get the metadata of a specified class

You can retrieve the metadata of the CryptoKey class in the default domain with a GET request. You can recursively retrieve the named resource object plus any directly or indirectly referenced classes and types to a specified depth.

GET https://example.com:5554/mgmt/metadata/default/CryptoKey?view=recursive&depth=2

The response shows the returned response payload that includes both the resource CryptoKey plus any directly or indirectly referenced classes and types down to a depth of 2. The references are included in an _embedded stanza that is included in the resource object. A descendants list is part of the _embedded stanza and contains the class metadata and type definitions.

  "_links": {
    "self": {
      "href": "/mgmt/metadata/default/CryptoKey"
    },
    "doc": {
      "href": "/mgmt/docs/metadata/CryptoKey"
    }
  },
  "object": {
   ...
   "_embedded": {
     "descendants": [
       {
         ...,
         "type": {
           "name": "dmAdminState",
           "value-list": {
             "value": [
               {
                 "name": "enabled",
                 "display": "enabled"
               },
               { 
                 "name": "disabled",
                 "display": "disabled"
               }
             ]
           },
           "cli-arg": "enabled | disabled"
         }
         ...
       }
     ]
  }
}

List the domains on the DataPower Gateway

The links are presented directly on the REST API root URI GET response.

GET https://example.com:5554/mgmt/domains/config/

The response returns in a structured list.

{
    "_links": {
       "self": {
         "href": "/mgmt/domains/config/"
       },
       "doc": {
          "href": "/mgmt/docs/config/domains"
       }
    },
    "domain": [
     {
        "name": "default",
        "href": "/mgmt/config/default/Domain/default"
     },
     {
        "name": "myDomain",
        "href": "/mgmt/config/default/Domain/myDomain"
     }
  ]
}

Create a domain

Retrieve the list of DataPower domains.
Determine that the domain wanted does not exist.

Create a domain test and set the AdminState to enabled.

PUT https://example.com:5554/mgmt/config/default/Domain/test

The payload indicates that the domain name is test.

{
  "Domain": {
    "name": "test",
    "mAdminState": "enabled"
  }
}

The response indicates that the configuration was created.

{
    "_links": {
       "self": {
          "href": "/mgmt/config/default/Domain/test"
       },
       "doc": {
          "href": "/mgmt/docs/config/Domain"
       }
    },
    "test": "Configuration has been created.
}

You can send a GET request to retrieve the list of domains on the DataPower Gateway to confirm that the domain test was successfully created.

Save the domain configuration

Save the running configuration of the test domain to the startup configuration.

POST https://example.com:5554/mgmt/actionqueue/test

The payload is as follows.

{
  "SaveConfig" : "0"
}

Use REST requests to retrieve the domain configuration and change settings

Request the configuration information.

GET https://example.com:5554/mgmt/config/default/Domain/myDomain

The response payload has the form.

{
    "_links": {
       "self": {
          "href": "/mgmt/config/default/Domain/myDomain"
       },
       "doc": {
          "href": "/mgmt/docs/config/Domain"
       }
    },
    "Domain": {
       "name": "myDomain",
       "mAdminState": "enabled",
       "FileMap": {
          "CopyFrom": "on",
          "CopyTo": "on",
          "Delete": "on",
          "Display": "on",
          "Exec": "on",
          "Subdir": "on"
       },
       "ConfigMode": "local",
       "ImportFormat": "XML",
       "LocalIPRewrite": "on",
      "MaxChkpoints": 3
    }
}

Change properties in the configuration with a PUT method. The value for MaxChkpoints properties is different from the value in the response with a GET method.

PUT https://example.com:5554/mgmt/config/default/Domain/myDomain
{
  "Domain": {
    "name": "myDomain",
    "mAdminState": "enabled",
    "ConfigMode": "local",
    "ImportFormat": "XML",
    "LocalIPRewrite": "on",
    "MaxChkpoints": 5
  }
}

The response payload has the form.

{
  "_links": {
    "self": {
      "href": "/mgmt/config/default/Domain/myDomain"
    },
    "doc": {
      "href": "/mgmt/docs/config/Domain"
    }
  },
  "myDomain": "Configuration updated."
}

Use a POST instead of a PUT request to create an object

A POST request differs from a PUT request in two ways. A POST request succeeds only if the target resource does not exist. If the resource exists, it returns an error. The POST request targets the parent class name, while a PUT request targets the resource. Compare this POST request with the previous PUT request example.

The payload of this POST request creates the TEST_deployment-policy configuration deployment policy when it does not exist. If the policy does not exist, the two modify statements set the HTTP handler port to 1979 and its local address to 192.0.2.0. The response indicates that the policy was created.

POST https://example.com:5554/mgmt/config/test-domain_1/ConfigDeploymentPolicy
{
  "ConfigDeploymentPolicy": {
    "name": "TEST_deployment-policy",
    "mAdminState": "enabled",
    "ModifiedConfig": [
      {
        "Match": "*/*/protocol/http?Name=TEST_FSH&Property=LocalPort",
        "Type": "change",
        "Property": "",
        "Value": 1979
      },
      {
        "Match": "*/*/protocol/http?Name=TEST_FSH&Property=LocalAddress",
        "Type": "change",
        "Property": "",
        "Value": "192.0.2.0"
      }
    ]
  }
}

The response payload has the form.

{
  "_links": {
    "self": {
      "href": "/mgmt/config/test-domain_1/ConfigDeploymentPolicy"
    },
    "doc": {
      "href": "/mgmt/docs/config/ConfigDeploymentPolicy"
    }
  },
  "TEST_deployment-policy": "Configuration has been created."
}

Delete an object

In this case, delete the configuration deployment policy TEST_deployment-policy. If you attempt to delete a system resource or an object that is in use by another object, the response contains the error details.

DELETE https://example.com:5554/mgmt/config/test-domain_1/ConfigDeploymentPolicy/TEST_deployment-policy
{
  "_links": {
    "self": {
      "href": "/mgmt/config/test-domain_1/ConfigDeploymentPolicy/TEST_deployment-policy"
    },
    "doc": {
      "href": "/mgmt/docs/config/ConfigDeploymentPolicy"
    }
  },
  "TEST_deployment-policy": "Configuration has been deleted."
}

Get or update the value of a scalar property

Retrieve the LocalPort value for the test-HTTP-SPH HTTP handler. The response contains the LocalPort as 8003.

GET https://example.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/test-HTTP-SPH/LocalPort
{
  links": {
    "self": {
      "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/test-HTTP-SPH/LocalPort
    },
    "doc": {
      "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"
    }
  },
  "LocalPort": 8003
}

Set the LocalPort to 8004 by using a PUT request. The target URI for the PUT request is identical to a GET request but LocalPort is updated based on the payload.
```
PUT https://example.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/test-HTTP-SPH/LocalPort
{
  "LocalPort": 8004
}
```

List the files in a directory

You can use a GET request to display the contents of the test-directory that is in the local: directory structure of the test-domain_1.

GET https://example.com:5554/mgmt/filestore/test-domain_1/local/test-directory

The response shows the file status information for the test-file file that exists in the test-directory directory.

{
  "_links": {
    "self": {
      "href": "/mgmt/filestore/test-domain_1/local/test-directory"
    },
    "doc": {
      "href": "/mgmt/docs/filestore"
    }
  },
  "filestore": {
    "location": {
      "name": "local:/test-directory",
      "file": {
        "name": "test-file",
        "size": 1182,
        "modified": "2015-04-07 15:14:17",
        "href":"/mgmt/filestore/test-domain_1/local/test-directory/test-file"
      }
    }
  },
  "href":"/mgmt/filestore/test-domain_1/local/test-directory"
}

Get the runtime states of all the objects in a class and their directly referenced objects

You use a GET request to retrieve the runtime state of every instance of the TLSClientProfile class in the my-testing-domain domain and its directly referenced objects.

GET https://example.com:5554/mgmt/config/my-testing-domain/TLSClientProfile?state=1

The response shows the runtime states of all the objects and their directly referenced objects in a specified class and domain.

{
  "_links": {
    "self": {
      "href": "/mgmt/config/my-testing-domain/TLSClientProfile?state=true"
    },
    "doc": {
      "href": "/mgmt/docs/config/TLSClientProfile"
    }
  },
  "TLSClientProfile": {
    "name": "test-tls-client",
    "_links": {
      "self": {
        "href": "/mgmt/config/my-testing-domain/TLSClientProfile/test-tls-client"
      },
      "doc": {
        "href": "/mgmt/docs/config/TLSClientProfile"
      }
    },
    "state": {
      "opstate": "up",
      "adminstate": "enabled",
      "eventcode": "0x00000000",
      "errorcode": "",
      "configstate": "new"
    },
    "mAdminState": "enabled",
    "Protocols": {
      "SSLv3": "off",
      "TLSv1d0": "on",
      "TLSv1d1": "on",
      "TLSv1d2": "on"
    },
    "Ciphers": [
      "ECDHE_RSA_WITH_AES_256_GCM_SHA384",
      ...
      "DHE_DSS_WITH_3DES_EDE_CBC_SHA",
      "RSA_WITH_3DES_EDE_CBC_SHA"
    ],
    "ValidateServerCert": "on",
    "Valcred": {
      "value": "test-valcreds",
      "href": "/mgmt/config/my-testing-domain/CryptoValCred/test-valcreds",
      "state": {
        "opstate": "up",
        "adminstate": "enabled",
        "eventcode": "0x00000000",
        "errorcode": "",
        "configstate": "new"
      }
    },
    "Caching": "on",
    "CacheTimeout": 300,
    "CacheSize": 100,
    "SSLClientFeatures": {
      "use-sni": "on",
      "permit-insecure-servers": "off",
      "compression": "off"
    },
    "EllipticCurves": [
      "secp521r1",
      "secp384r1",
      "secp256k1",
      "secp256r1"
    ],
    "UseCustomSNIHostname": "no"
  }
}

Get a specified object configuration and recursively GET its referenced objects

You can retrieve recursively the configuration for the eg-Firewall object of the XMLFirewallService class in the amp domain. The GET request retrieves the configuration of the XML firewall service to a depth of 3.

GET https://example.com:5554/mgmt/config/amp/XMLFirewallService/eg-Firewall?view=recursive&depth=3

The response shows the configuration object retrieved. The response contains all the object properties (such as _links) and the referenced objects (such as XMLFirewallService and _embedded), up to a depth of 3. Referenced objects are nested in the _embedded resource objects. A partial payload is returned if the specified depth is reached even though deeper referenced objects exist. The result does not indicate whether objects exist at a level that is deeper than the maximum depth.

"_embedded": {
  "descendants": [
    {
      "_links": {
        "self": {
          "href": "/mgmt/config/rest-mgmt/XMLManager/default"
        },
        "doc": {
          "href": "/mgmt/docs/config/XMLManager"
        }
      },
      "XMLManager": {
        "name": "default",
        "mAdminState": "enabled",
        "UserSummary": "Default XML-Manager",
        "CacheSize": 256,
        "SHA1Caching": "on",
        "StaticDocumentCalls": "on",
        "SearchResults": "on",
        "SupportTxWarn": "off",
        "ParserLimitsBytesScanned": 4194304,
        "ParserLimitsElementDepth": 512,
        "ParserLimitsAttributeCount": 128,
        "ParserLimitsMaxNodeSize": 33554432,
        "ParserLimitsExternalReferences": "forbid",
        "ParserLimitsMaxPrefixes": 1024,
        "ParserLimitsMaxNamespaces": 1024,
        "ParserLimitsMaxLocalNames": 60000,
        "DocCacheMaxDocs": 5000,
        "DocCacheSize": 0,
        "DocMaxWrites": 32768,
        "UserAgent": {
          "value": "default",
          "href": "/mgmt/config/rest-mgmt/HTTPUserAgent/default"
        }
      }
    },
      ...
  ]
}

Create new directories and files with either POST or PUT requests

You can use a POST request to create the directory test-directory in the local: directory of the test-domain_1.

POST https://example.com:5554/mgmt/filestore/test-domain_1/local
{
  "directory": {
    "name": "test-directory"
  }
}

The response contains the message that the test-directory was created successfully.

{
  "_links": {
    "self": {
      "href": "/mgmt/filestore/test-domain_1/local"
    },
    "doc": {
      "href": "/mgmt/docs/filestore"
    }
  },
  "result": "Directory local:/test-directory has been created."
}

Similar to the POST mechanism, you can create another subdirectory in the local directory that is called test-directory_2 with a PUT request. The new subdirectory name appears in the URI.

PUT https://example.com:5554/mgmt/filestore/test-domain_1/local
{
  "directory": {
    "name": "test-directory_2"
  }
}

The response shows that the directory test-directory_2 was created in the local directory.

{
  "_links": {
    "self": {
      "href": "/mgmt/filestore/test-domain_1/local/test-directory_2"
    },
    "doc": {
      "href": "/mgmt/docs/filestore"
    }
  },
    "result": "Directory local:/test-directory_2 has been created."
}

After the response returns the success message, you can use a GET request to validate that the new directories exist in the local directory.

GET https://example.com:5554/mgmt/filestore/test-domain_1/local

The response shows that the local directory contains both test-directory_2 and test-directory.

{
  "_links": {
    "self": {
      "href": "/mgmt/filestore/test-domain_1/local"
    },
    "doc": {
      "href": "/mgmt/docs/filestore"
    }
  },
  "filestore": {
    "location": {
      "name": "local:",
      "directory": [
        {
          "name": "local:/test-directory_2",
          "href": "/mgmt/filestore/test-domain_1/local/test-directory_2"
        },
        {
          "name": "local:/test-directory",
          "href": "/mgmt/filestore/test-domain_1/local/test-directory"
        }
      ],
    "href": "/mgmt/filestore/test-domain_1/local"
    }
  }
}

When you create files, the contents of the payload file must be Base64 encoded. If the contents are not Base64 encoded, a schema validation error occurs. The first PUT request creates the file and the second PUT request overwrites the file. The response indicates that the file was created and then updated by the second request.

PUT https://example.com:5554/mgmt/filestore/test-domain_1/local/test-file
{
  "file": {
    "name":"test-file",
    "content":"dG9wOyBjb25maWd1cmUgdGVybWluYWw7CgojIGNvbmZpZ3VyYXRpb
               24gZ2VuZX4gOSAxMjowMludGVyZmFjZSAiZXRoMTAgYXJwCiAgaXB
               2NgogIG5vIHNsYWFjCiAgbXR1ICIxNTAwIgogIGlwdjYtbGlua2xv
               Y2FsLXN0YXJ0dXAtd28tcHJpbWFyeS1pcGFkZHIKICBhZG1pbi1zd
               GF0ZSAiZW5hYmxlZCIKZXhpdCAKCmludGVyZmFjZSAiZXRoMjAi..."
   }
}
{
  "_links": {
    "self": {
      "href": "/mgmt/filestore/test-domain_1/local/test-file"
    },
    "doc": {
       "href": "/mgmt/docs/filestore"
    }
  },
  "result": "File local:/test-file has been created."
}

The response to the same request with an updated payload indicates that the file was updated with the last request payload that was sent in. The update content is in the payload.

PUT https://example.com:5554/mgmt/filestore/test-domain_1/local/test-file
{
  "file": {
    "name":"test-file",
    "content":"KZXhpdCAKCmludGVyZmFjZSAiZXRoMjBi..."
  }
}
{
  "_links": {
    "self": {
      "href": "/mgmt/filestore/test-domain_1/local/test-file"
    },
    "doc": {
      "href": "/mgmt/docs/filestore"
    }
  },
  "result": "File local:/test-file has been updated."
}

Samples that use the REST management interface

Use the curl program to request a list of all active users on the DataPower Gateway

Use the curl program to request various kinds of time and day status for the DataPower Gateway

Use a curl command to move the files between directories

Get the status root

List the supported actions at the actionqueue operations URI

Recursively get the metadata of a specified class

List the domains on the DataPower Gateway

Create a domain

Save the domain configuration

Use REST requests to retrieve the domain configuration and change settings

Use a POST instead of a PUT request to create an object

Delete an object

Get or update the value of a scalar property

List the files in a directory

Get the runtime states of all the objects in a class and their directly referenced objects

Get a specified object configuration and recursively GET its referenced objects

Create new directories and files with either POST or PUT requests

List the supported actions at the `actionqueue` operations URI