White Papers
Abstract
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.
Content
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. 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: 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 When you access the filestore root URI, Listing 2 shows the required URI structure to manipulate individual files and directories on the appliance. You can perform all directory manipulation operations. These operations include retrieving the contents of existing directories, creating directories and subdirectories, and deleting existing directories. 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 Listing 3 shows that the target directory contains one file, test-file, and the relevant information for that file. 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 The following PUT request shows the URI that is required to create a test-directory subdirectory within the 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 After the directory is created, you see a response similar to the example in Listing 5. 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. To delete an existing directory, send an HTTP DELETE request to the target directory. The following example request shows the After the directory is deleted, you see a response similar to the example in Listing 6. You can perform all file manipulation operations. These operations include retrieving and updating the contents of existing files, creating files, and deleting existing files. 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 Listing 7 shows the file contents that are returned as a base64-encoded payload. 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 The following PUT request shows the URI that is required to create the test-file file in the 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 specified appropriately in the After the file is created, a response is returned similar to the one shown in Listing 9. To update an existing file resource, issue the following PUT request to the target file: The existing file is overwritten with the payload contents as shown in Listing 10. 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 After the file is deleted, a response is returned that is similar to the example in Listing 11. 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. See the other parts in this series: The following links are helpful when reading this tutorial:Introduction
File system navigation
GET https://dphost.com:5554/mgmt/
/mgmt/filestore/
URI.
{ "_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/" } } }
/mgmt/filestore/
, by using the following request, you see the available options for the appliance filestore resource:
GET https://dphost.com:5554/mgmt/filestore/
{ "_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
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
{ "_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" } } }
local:///
directory in test-domain_1
:
POST https://dphost.com:5554/mgmt/filestore/test-domain_1/local
local:///
directory in test-domain_1
:
PUT https://dphost.com:5554/mgmt/filestore/test-domain_1/local/test-directory
name
parameter. This payload 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.
{ "directory": { "name": "test-directory" } }
{ "_links": { "self": { "href": "/mgmt/filestore/test-domain_1/local" }, "doc": { "href": "/mgmt/docs/filestore" } }, "test-directory": "Directory has been created." }
local:///test_dir
directory in the default
domain:
DELETE https://dphost.com:5554/mgmt/filestore/default/local/test_dir
{ "_links": { "self": { "href": "/mgmt/filestore/default/local/test_dir" }, "doc": { "href": "/mgmt/docs/filestore" } }, "result": "ok", "script-log": "" }
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
{ "_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=..." } }
local:///
directory in test-domain_1
:
POST https://dphost.com:5554/mgmt/filestore/test-domain_1/local
local:///
directory in test-domain_1
:
PUT https://dphost.com:5554/mgmt/filestore/test-domain_1/local/test-file
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.
{ "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" } }, "test-file": "File has been created." }
PUT https://dphost.com:5554/mgmt/filestore/test-domain_1/local/test-file
{ "_links": { "self": { "href": "/mgmt/filestore/test-domain_1/local/test-file" }, "doc": { "href": "/mgmt/docs/filestore" } }, "test-file": "File has been updated." }
local:///test_dir
directory in the default
domain:
DELETE https://dphost.com:5554/mgmt/filestore/default/local/test_dir/test_file.txt
{ "_links": { "self": { "href": "/mgmt/filestore/default/local/test_dir/test_file.txt" }, "doc": { "href": "/mgmt/docs/filestore" } }, "result": "ok" }
Conclusion
Resources
Was this topic helpful?
Document Information
Modified date:
08 June 2021
UID
ibm11109691