DELETE

Use the HTTP DELETE method with the queue resource to delete a specified queue on a specified queue manager.

This REST API command is similar to the Delete Queue PCF command, and the DELETE queues MQSC commands.

Resource URL
Optional query parameters
Request headers
Request body format
Security requirements
Response status codes
Response headers
Response body format
Examples

Resource URL

[V9.0.4 Oct 2017] IBM® MQ 9.0.4 and later:

https://host:port/ibmmq/rest/v1/admin/qmgr/{qmgrName}/queue/{queueName}

IBM MQ 9.0.3 and earlier:

https://host:port/ibmmq/rest/v1/qmgr/{qmgrName}/queue/{queueName}

qmgrName

Specifies the name of the queue manager on which the queue to delete exists.

You can specify a remote queue manager as the qmgrName. If you specify a remote queue manager, you must configure a gateway queue manager. For more information, see Remote administration using the REST API.

The queue manager name is case-sensitive.

If the queue manager name includes a forward slash, a period, or a percent sign, these characters must be URL encoded:

A forward slash (/) must be encoded as %2F.
A percent sign (%) must be encoded as %25.

queueName

Specifies the name of the queue to delete.

The queue name is case-sensitive.

If the queue name includes a forward slash or a percent sign, these characters must be URL encoded:

A forward slash, /, must be encoded as %2F.
A percent sign, %, must be encoded as %25.

[V9.0.1 Nov 2016] You can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configuring HTTP and HTTPS ports.

Optional query parameters

keepAuthorityRecords

This parameter is only available on the IBM MQ Appliance, UNIX, Linux®, and Windows.

Specifies that the associated authority records are not deleted.

commandScope=scope

This parameter is only available on z/OS®.

Specifies how the command is run when the queue manager is a member of a queue-sharing group.

You cannot specify this parameter if the queue manager is not a member of a queue-sharing group.

scope can be one of the following values:

The name of a queue manager

Specifies that the command is run on the queue manager that is named. The queue manager must be active within the same queue sharing group as the queue manager that is specified in the resource URL.

You cannot specify the queue manager name that is the queue manager that is specified in the resource URL.

If the queue manager name includes a percent sign, %, this character must be URL encoded as %25.

*

Specifies that the command is run on the local queue manager and also passed to every active queue manager in the queue sharing group.

If this option is used, an ibm-mq-qmgrs response header is returned with a comma-separated list of the queue managers that generated a response. For example, the header might look like the following header:

ibm-mq-qmgrs: MQ21, MQ22

purge

Specifies that all messages are purged from the queue.

If messages are on the queue, you must specify purge, or the queue cannot be deleted.

queueSharingGroupDisposition=disposition

This parameter is only available on z/OS.

Specifies where the queue is defined and how it behaves. That is, it specifies the disposition of the queue.

disposition can be one of the following values:

copy

Specifies that the queue definition exists on the page set of the queue manager that runs the command. The queue was defined by a command that used the MQQSGD_COPY PCF parameter, or the copy REST API parameter.

Any queue in the shared repository, or any queue that is defined by using the MQQSGD_Q_MGR PCF parameter, or qmgr REST API parameter, is not affected by this command.

group

Specifies that the queue definition exists in the shared repository. The queue was defined by a command that used the MQQSGD_GROUP PCF parameter, or the group REST API parameter.

Any queue that exists on the page set of the queue manager that runs the command, except for a local copy of the queue, is not affected by this command.

If the deletion is successful, the following MQSC command is generated and sent to all active queue managers in the queue sharing group to delete local copies on page set zero:

DELETE queue(q-name) QSGDISP(COPY)

or for a local queue only:

DELETE QLOCAL(q-name) NOPURGE QSGDISP(COPY)

The deletion of the group object takes effect even if the generated command with QSGDISP(COPY) fails.

Note: You always get the NOPURGE option even if you specify the purge flag. To delete messages on local copies of the queues you must explicitly run, for each copy, a command to delete the queue with the purge flag, and a queueSharingGroupDisposition value of copy.

qmgr

Specifies that the queue definition exists on the page set of the queue manager that runs the command. The object was defined by a command that used the MQQSGD_Q_MGR PCF parameter or the qmgr REST API parameter.

Any queue that exists in the shared repository, or any local copy of such a queue, is not affected by this command.

shared

This value is only valid for local queues.

Specifies that the queue exists in the shared repository. The object was defined by a command that used the MQQSGD_SHARED PCF parameter or the shared REST API parameter.

Any queue that exists on the page set of the queue manager that runs the command, or any queue that is defined by a command that uses the parameter MQQSGD_GROUP is not affected by this command.

The default value is qmgr.

Request headers

The following headers must be sent with the request:

ibm-mq-rest-csrf-token: This header must be sent with a value that is the content of the csrfToken cookie. The content of the csrfToken cookie is used to confirm that the credentials that are being used to authenticate the request are being used by the owner of the credentials. That is, the token is used to prevent cross-site request forgery attacks.; The csrfToken cookie is returned after a request is made with an HTTP GET method. You cannot use a cached version of the content of the cookie because the content of the cookie can change. You must use the latest value of the cookie for each request.; The preceding information applies to releases up to and including IBM MQ 9.0.4. From IBM MQ 9.0.5, this header must be set, but the value can be anything, including being blank.
The csrfToken cookie is no longer sent in responses from the REST API in IBM MQ 9.0.5 and later.
Authorization: This header must be sent if you are using basic authentication. For more information, see Using HTTP basic authentication with the REST API.

The following headers can optionally be sent with the request:

ibm-mq-rest-gateway-qmgr: This header specifies the queue manager that is to be used as the gateway queue manager. The gateway queue manager is used to connect to a remote queue manager. For more information, see Remote administration using the REST API.

Request body format

None.

Security requirements

The caller must be authenticated to the mqweb server and must be a member of one or more of the MQWebAdmin, MQWebAdminRO, or MQWebUser roles. For more information about security for the administrative REST API, see IBM MQ Console and REST API security.

The security principal of the caller must be granted the ability to issue the following PCF commands for the specified queue manager:

For the queue that is specified by the {queueName} portion of the resource URL, authority to issue the MQCMD_DELETE_Q PCF command must be granted.

[UNIX, Linux, Windows] On UNIX, Linux, and Windows, you can grant authority to security principals to use IBM MQ resources by using the mqsetaut command. For more information, see mqsetaut.

[z/OS] On z/OS, see Setting up security on z/OS.

Response status codes

204: Queue deleted successfully.
400: Invalid data provided.; For example, invalid queue data is specified, or the queue is not empty.
401: Not authenticated.; The caller must be authenticated to the mqweb server and must be a member of one or more of the MQWebAdmin, MQWebAdminRO, or MQWebUser roles. The ibm-mq-rest-csrf-token header must also be specified. For more information, see Security requirements.
403: Not authorized.; The caller is authenticated to the mqweb server and is associated with a valid principal. However, the principal does not have access to all, or a subset of the required IBM MQ resources. For more information about the access that is required, see Security requirements.
404: Queue does not exist.
500: Server issue or error code from IBM MQ.
503: Queue manager not running.

Response headers

The following headers are returned with the response:

ibm-mq-qmgrs

On z/OS, if the optional query parameter commandScope=* is used, this header is returned with a comma-separated list of the queue managers that generated a response. For example, the header might look like the following header:

ibm-mq-qmgrs: MQ21, MQ22

If an error occurs before the command is issued to the queue managers, the response header does not contain the list of queue managers. For example, a request that generates a 200 or 201 status code has the header because the command was successful. A request that generates a 401 (not authenticated) status code does not have the header because the request was rejected. A request that generates a 403 (not authorized) status code has the header because individual queue managers decide whether the command is authorized.

ibm-mq-rest-gateway-qmgr

This header is returned if a remote queue manager is specified in the resource URL. The value of this header is the name of the queue manager that is used as the gateway queue manager.

Response body format

The response body is empty if the queue is deleted successfully. If an error occurs, the response body contains an error message. For more information, see REST API error handling.

Examples

The following example deletes the queue Q1 from the queue manager QM1, and purges all messages from the queue when used with the HTTP DELETE method:

IBM MQ 9.0.4 and later:

https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue/Q1?purge

IBM MQ 9.0.3 and earlier:

https://localhost:9443/ibmmq/rest/v1/qmgr/QM1/queue/Q1?purge