REST management interface and IBM DataPower

Gateway: Part 3: File and directory management

Anna Derbakova December 07, 2015

This tutorial series explains how to use the REST management interface to manage and
monitor the configuration of IBM® DataPower® Gateway appliances. It describes the
functions, structure, and capabilities of the REST management interface, as implemented
in firmware release 7.2.0.0. In the first two parts, you learned about the basic concepts of
the REST management interface and how to use it to monitor status and manage appliance
configurations. In Part 3, you learn how to manage files and directories by using the REST
management interface.
View more content in this series

Introduction
The REST management interface offers end-to-end file and directory management capabilities in
firmware release 7.2.0.0 of the IBM DataPower Gateway Appliance. In Part 3 of this series, you
learn about specific file system requests. You learn about directory management, including how
to retrieve the contents of an existing directory and how to create and delete directories. You also
learn about file management, including how to retrieve file contents, create and update files, and
delete files. For information about other request types, such as status monitoring, configuration
management, and appliance operations, see the other parts in this series.

File system navigation

To begin retrieving and modifying existing file system resources, you must become familiar with the
filestore resource of the REST management interface that represents the appliance file system.
You can find the filestore resource by accessing the root Uniform Resource Identifier (URI) of the
REST management interface, as shown by the following request:
GET https://dphost.com:5554/mgmt/

Listing 1 shows the response that is received from the root URI. The response shows the available
resource categories on the appliance. The filestore resource is identified by the /mgmt/filestore/
URI.

Listing 1. Root URI response

{

© Copyright IBM Corporation 2015 Trademarks

REST management interface and IBM DataPower Gateway: Part Page 1 of 8
3: File and directory management
developerWorks® ibm.com/developerWorks/

"_links": {
"self": {
"href": "/mgmt/"
},
"config": {
"href": "/mgmt/config/"
},
"domains": {
"href": "/mgmt/domains/config/"
},
"status": {
"href": "/mgmt/status/"
},
"actionqueue": {
"href": "/mgmt/actionqueue/"
},
"filestore": {
"href": "/mgmt/filestore/"
},
"metadata": {
"href": "/mgmt/metadata/"
},
"types": {
"href": "/mgmt/types/"
}
}
}

When you access the filestore root URI, /mgmt/filestore/, by using the following request, you see
the available options for the appliance filestore resource:
GET https://dphost.com:5554/mgmt/filestore/

Listing 2 shows the required URI structure to manipulate individual files and directories on the
appliance.

Listing 2. Filestore root URI response

{
"_links": {
"self": {
"href": "/mgmt/filestore/"
},
"top": {
"href": "/mgmt/filestore/{domain}/{top_directory}"
},
"directory": {
"href": "/mgmt/filestore/{domain}/{top_directory}/{directory_path}"
},
"file": {
"href": "/mgmt/filestore/{domain}/{top_directory}/{file_path}"
}
}
}

Directory management
You can perform all directory manipulation operations. These operations include retrieving the
contents of existing directories, creating directories and subdirectories, and deleting existing
directories.

REST management interface and IBM DataPower Gateway: Part Page 2 of 8

3: File and directory management
ibm.com/developerWorks/ developerWorks®

Retrieve directory contents

You can retrieve the contents of any appliance directory if you have appropriate access
permissions to that directory. To retrieve the contents of any directory, construct a URI according
to the directory link in Listing 2. The following request shows an example in which the local:///
test-directory directory is accessed within test-domain_1:

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

Listing 3 shows that the target directory contains one file, test-file, and the relevant information for
that file.

Listing 3. Retrieve directory contents response

{
"_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"
}
}
}

Create directories
You can create a directory with a PUT request or a POST request. Both requests accomplish
the same operation, but require a different URI to complete successfully. You can choose which
approach is more convenient for you. The following POST request shows the URI that is required
to create a subdirectory in the local:/// directory in test-domain_1:
POST https://dphost.com:5554/mgmt/filestore/test-domain_1/local

The following PUT request shows the URI that is required to create a test-directory subdirectory
within the local:/// directory in test-domain_1:
PUT https://dphost.com:5554/mgmt/filestore/test-domain_1/local/test-directory

Both URIs in the POST and PUT requests accomplish the same objective if the subdirectory
names to be created are the same. Listing 4 shows the required request payload for this request,
where the directory name must be specified appropriately in the name parameter. This payload

REST management interface and IBM DataPower Gateway: Part Page 3 of 8

3: File and directory management
developerWorks® ibm.com/developerWorks/

structure is used for both the PUT request and the POST request. The directory name in the
payload and the URI for the PUT request must match. Otherwise, an error results.

Listing 4. Create directory request payload

{
"directory": {
"name": "test-directory"
}
}

After the directory is created, you see a response similar to the example in Listing 5.

Listing 5. Create directory response

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

The POST request and the PUT request on an existing directory resource do not allow you to
overwrite the directory. This feature protects you from accidentally removing the directory contents.
If you intend to overwrite a directory with new contents, you must first delete the directory by
issuing a DELETE request and then re-create it.

Delete existing directories

To delete an existing directory, send an HTTP DELETE request to the target directory. The
following example request shows the local:///test_dir directory in the default domain:
DELETE https://dphost.com:5554/mgmt/filestore/default/local/test_dir

After the directory is deleted, you see a response similar to the example in Listing 6.

Listing 6. Delete directory response

{
"_links": {
"self": {
"href": "/mgmt/filestore/default/local/test_dir"
},
"doc": {
"href": "/mgmt/docs/filestore"
}
},
"result": "ok",
"script-log": ""
}

REST management interface and IBM DataPower Gateway: Part Page 4 of 8

3: File and directory management
ibm.com/developerWorks/ developerWorks®

File management
You can perform all file manipulation operations. These operations include retrieving and updating
the contents of existing files, creating files, and deleting existing files.

Retrieve file contents

You can retrieve the contents of any file on the appliance, if you have appropriate access
permissions to that file. To retrieve the contents of any file, construct a URI according to the file
link in Listing 2. The following request retrieves contents of the test_file.txt file in the local:///
test_dir directory in the default domain:

GET https://dphost.com:5554/mgmt/filestore/default/local/test_dir/test_file.txt

Listing 7 shows the file contents that are returned as a base64-encoded payload.

Listing 7. Retrieve file contents response

{
"_links": {
"self": {
"href": "/mgmt/filestore/default/local/test_dir/test_file.txt"
},
"doc": {
"href": "/mgmt/docs/filestore"
}
},
"file": {
"name": "local:///test_dir/test_file.txt",
"value": "SEVMTE8hISE=..."
}
}

Create and update files

You can create a file by using a PUT request or a POST request. Both requests accomplish the
same operation, but require a different URI to complete successfully. Use the POST request to
create files because a POST request results in a failure if a file with the same name exists in the
target directory. This feature prevents you from accidentally overwriting an existing file. However,
you can also create a file by using a PUT request. Issuing a PUT request on an existing file
overwrites the file with the contents in the request payload.

The following POST request shows the URI that is required to create a file in the local:///
directory in test-domain_1:
POST https://dphost.com:5554/mgmt/filestore/test-domain_1/local

The following PUT request shows the URI that is required to create the test-file file in the
local:/// directory in test-domain_1:

PUT https://dphost.com:5554/mgmt/filestore/test-domain_1/local/test-file

Both URIs accomplish the same objective if the file names to be created are the same. Listing
8 shows the required request payload for this request. Here, the file name and content must be

REST management interface and IBM DataPower Gateway: Part Page 5 of 8

3: File and directory management
developerWorks® ibm.com/developerWorks/

specified appropriately in the name and content parameters. The file contents must be base64-
encoded before they are embedded into the request payload. Use this payload structure for both
the PUT request and the POST request. The file name in both the payload and URI for the PUT
request must match. Otherwise, an error will result.

Listing 8. Create file request payload

{
"file": {
"name":"test-file",
"content":"dG9wOyBjb25maWd1cmUgdGVybWluYWw7CgojIGNvbmZpZ3VyYXRpb
24gZ2VuZX4gOSAxMjowMludGVyZmFjZSAiZXRoMTAgYXJwCiAgaXB
2NgogIG5vIHNsYWFjCiAgbXR1ICIxNTAwIgogIGlwdjYtbGlua2xv
Y2FsLXN0YXJ0dXAtd28tcHJpbWFyeS1pcGFkZHIKICBhZG1pbi1zd
GF0ZSAiZW5hYmxlZCIKZXhpdCAKCmludGVyZmFjZSAiZXRoMjAi..."
}
}

After the file is created, a response is returned similar to the one shown in Listing 9.

Listing 9. Create file response

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

To update an existing file resource, issue the following PUT request to the target file:
PUT https://dphost.com:5554/mgmt/filestore/test-domain_1/local/test-file

The existing file is overwritten with the payload contents as shown in Listing 10.

Listing 10. Update file response

{
"_links": {
"self": {
"href": "/mgmt/filestore/test-domain_1/local/test-file"
},
"doc": {
"href": "/mgmt/docs/filestore"
}
},
"test-file": "File has been updated."
}

Delete existing files

To delete an existing file, send an HTTP DELETE request to the target file. The following example
shows this request for the test_file.txt file in the local:///test_dir directory in the default
domain:

REST management interface and IBM DataPower Gateway: Part Page 6 of 8

3: File and directory management
ibm.com/developerWorks/ developerWorks®

DELETE https://dphost.com:5554/mgmt/filestore/default/local/test_dir/test_file.txt

After the file is deleted, a response is returned that is similar to the example in Listing 11.

Listing 11. Delete file response

{
"_links": {
"self": {
"href": "/mgmt/filestore/default/local/test_dir/test_file.txt"
},
"doc": {
"href": "/mgmt/docs/filestore"
}
},
"result": "ok"
}

Conclusion
In this tutorial, you learned about the file and directory management capabilities through the REST
management interface for the IBM DataPower Gateway Appliance. You learned how to navigate
the appliance file system, how to retrieve the contents of existing files and directories, and how
to remove existing resources. You also learned how to compose valid request payloads to create
file system resources on the appliance. As you continue in this tutorial series, Part 4 explains the
operations that are available through the REST management interface for the DataPower Gateway
Appliance.

Resources
See the other parts in this series:

• REST management interface and IBM DataPower Gateway, Part 1: Introduction to the
interface and status monitoring
• REST management interface and IBM DataPower Gateway, Part 2: Configuration
management
• REST management interface and IBM DataPower Gateway, Part 3: File and directory
management
• REST management interface and IBM DataPower Gateway, Part 4: Triggering appliance
operations
The following links are helpful when reading this tutorial:

• To get started with the REST management interface, see Enabling the REST management
interface.
• For everything related to the REST management interface, see REST management interface.
• For example requests and responses from the REST management interface, see Samples
that use the REST management interface.
• For DataPower SOA Appliances 7.2.0 documentation, see the IBM Knowledge Center.
• For DataPower tutorials in the developerWorks® WebSphere® zone, see the Technical
Library.

REST management interface and IBM DataPower Gateway: Part Page 7 of 8

3: File and directory management
developerWorks® ibm.com/developerWorks/

• For the latest news and information, see the IBM developerWorks WebSphere zone.

© Copyright IBM Corporation 2015

(www.ibm.com/legal/copytrade.shtml)
Trademarks
(www.ibm.com/developerworks/ibm/trademarks/)

REST management interface and IBM DataPower Gateway: Part Page 8 of 8

3: File and directory management