Managing files by using the REST management interface

You can use the REST management interface to manipulate files and directories on the IBM® MQ Appliance.

When you use the REST management interface for this purpose, you send HTTP requests to the REST interface port and receive JSON-formatted responses with a payload and indication of success or failure. You can incorporate requests into programs and so automate interaction with the appliance.

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 format of the filestore resource by accessing the Uniform Resource Identifier (URI) of the filestore, as shown by the following example:

GET https://mqhost.com:5554/mgmt/filestore/

The following information is returned, which shows the required URI structure to manipulate individual files and directories on the appliance:

{
       "_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 sub-directories, and deleting existing directories. As with all other REST requests on the IBM MQ Appliance, these requests specify the default domain.

Retrieving the contents of a directory

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 the filestore resource listing. The following request shows an example in which the local:///test-directory directory is accessed in the default domain:

GET https://mqhost.com:5554/mgmt/filestore/default/local/test-directory

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

{
  "_links": {
    "self": {
      "href": "/mgmt/filestore/default/local/test-directory"
    },
    "doc": {
      "href": "/mgmt/docs/filestore"
    }
  },
  "filestore": {
    "location": {
      "name": "local:/test-directory",
      "file": {
        "name": "test-file",
        "size": 1182,
        "modified": "2016-04-07 15:14:17",
        "href":"/mgmt/filestore/default/local/test-directory/test-file"
      },
      "href":"/mgmt/filestore/default/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:

POST https://mqhost.com:5554/mgmt/filestore/default/local

The following PUT request shows the URI that is required to create a test-directory subdirectory within the local:/// directory:

PUT https://mqhost.com:5554/mgmt/filestore/default/local/test-directory

Both the POST and PUT requests require that the details of the directory to be created are specified in the request payload. The following example shows the required request payload, with the directory name specified in the name parameter. This payload structure is used for both the PUT request and the POST request. The directory name in the payload and in the URI for the PUT request must match, otherwise an error results.

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

Issuing a POST request or a PUT request on an existing directory resource returns an error. 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 a DELETE request to the target directory. The following example request requests deletion of the local:///test_dir directory:

DELETE https://mqhost.com:5554/mgmt/filestore/default/local/test_dir

After the directory is deleted, you see a response similar to the following example:

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

File management

You can perform all file manipulation operations by using the REST management interface. 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 provided you have appropriate access permissions to that file. To retrieve the contents of any file, construct a URI based on the file part of the filestore resource. For example, the following request retrieves contents of the test_file.txt file in the local:///test_dir directory:

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

File contents that are returned as a base64-encoded payload:

{
  "_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 create a file, but require a different URI to complete successfully. A POST request fails 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:

POST https://mqhost.com:5554/mgmt/filestore/default/local

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

PUT https://mqhost.com:5554/mgmt/filestore/default/local/test-file.txt

Both the POST and PUT requests require that the details of the file to be created are specified in the request payload. The following example shows the required request payload, with the file name specified in the name parameter and the contents in the contents parameter. The file contents must be base64-encoded before they are embedded into the request payload. This payload structure is used for both the PUT request and the POST request. The file name in the payload and in the URI for the PUT request must match, otherwise an error results.

{
  "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 the following example:

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

If you use a PUT request to overwrite an existing file, you receive a response similar to the following example:

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

Delete existing files

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

DELETE https://mqhost.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 following example:

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