Getting started with the REST API for MFT

Get started quickly with the administrative REST API for Managed File Transfer and try out a few example requests to view the MFT agent status, and to view a list of transfers.

Before starting

• The examples use cURL to send REST requests to view a list of transfers and view MFT agent status. Therefore, to complete this task you need cURL installed on the system.
• To complete this task, we must be a user with certain privileges so that we can use the dspmqweb command:
  • On z/OS, we must have authority to run the dspmqweb command, and write access to the mqwebuser.xml file.
  • On all other operating systems, we must be a privileged user.

Procedure

1. Ensure that the mqweb server is configured for the administrative REST API for MFT:
   • If the mqweb server is not already configured for use by the administrative REST API, the administrative REST API for MFT, the messaging REST API, or IBM MQ Console, configure the mqweb server.For more information about creating a basic configuration for the mqweb server with a basic registry, see Basic configuration for the mqweb server.
   • If the mqweb server is configured, ensure that step 8 of Basic configuration for the mqweb server was completed to enable the administrative REST API for MFT.

2. On z/OS, set the WLP_USER_DIR environment variable so that we can use the dspmqweb command. Set the variable to point to your mqweb server configuration by entering the following command:

   export WLP_USER_DIR=WLP_user_directory

   where WLP_user_directory is the name of the directory that is passed to crtmqweb. For example:

   export WLP_USER_DIR=/var/mqm/web/installation1

   For more information, see Create the mqweb server.

3. Determine the REST API URL by entering the following command:

   dspmqweb status

   The examples in the following steps assume that your REST API URL is the default URL https://localhost:9443/ibmmq/rest/v1/. If your URL is different than the default, substitute your URL in the following steps.
4. Make a GET request on the agent resource to return basic details about all agents, including the name, type and state:

   curl -k https://localhost:9443/ibmmq/rest/v2/admin/mft/agent/ -X GET -u mftadmin:mftadmin

5. Create some transfers to display by using the fteCreateTransfer command.

   The mqweb server caches information about transfers and returns this information when a request is made. This cache is reset when the mqweb server is restarted. We can see whether the server was restarted by viewing the console.log and messages.log files, or on z/OS, looking at the output from the started task.

6. Make a GET request on the transfer resource to return details of up to four transfers that were made since the mqweb server was started:

   curl -k https://localhost:9443/ibmmq/rest/v2/admin/mft/transfer?limit=4 -X GET -u mftadmin:mftadmin

What to do next

• The examples use basic authentication to secure the request. We can use token-based authentication or client-based authentication instead. For more information, see Use token-based authentication with the REST API, and Use client certificate authentication with the REST API and IBM MQ Console.
• Learn more about using the administrative REST API and constructing URLs with query parameters: Use the administrative REST API.
• Browse the reference information for the available administrative REST API for MFT resources and all the available optional query parameters: administrative REST API reference.
• Discover the messaging REST API, a RESTful interface for IBM MQ messaging: Messaging using the REST API.
• Discover the IBM MQ Console, a browser-based GUI: Administration using a web console.

Parent topic: Getting started with the administrative REST API