POST

Use the HTTP POST method with the queue resource to create a queue on a specified queue manager.

Note: This resource URL is available only in version 1 of the REST API. To create queues using version 2 of the REST API, use the /admin/action/qmgr/{qmgrName}/mqsc resource.

This REST API command is similar to the Change, Copy, and Create Queue PCF command, and the DEFINE 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

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

qmgrName

Specifies the name of the queue manager on which to create the queue.

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

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.
A period (.) must be encoded as %2E.

We can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configure HTTP and HTTPS ports.

Optional query parameters

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.

We 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.

We 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

like=qName

Specifies an existing queue definition to copy.

On z/OS, the way that a queue is copied depends on the value that is specified for the disposition parameter in the request body:

If copy is specified, the like parameter is ignored. The queue to copy is a queue with the name that is specified by the name parameter in the request body and with a disposition of group.
If copy is not specified, the queue to copy is a queue with the name that is specified by the like parameter and a disposition of qmgr, copy, or shared.

noReplace

Specifies that the queue is not replaced if it exists. If this flag is not specified, the queue is replaced.

If a queue is replaced, any messages that are on the existing queue are retained.

The queue is not replaced in the following scenarios:

The queue is a local queue. allowedSharedInput is changed to false, and more than one application has the local queue open for input.
The queue is a local queue. The value of isTransmissionQueue is changed, and one or more applications has the local queue open, or if one or more messages are on the queue.
The queue is a remote queue. The value of transmissionQueueName is changed, and an application has a remote queue open that would be affected by this change.
The queue is a remote queue. The value of queueName, qmgrName, or transmissionQueueName is changed, and one or more applications has a queue open that resolved through this definition as a queue manager alias.

Request headers

The following headers must be sent with the request:

Content-Type: This header must be sent with a value of application/json optionally followed by ;charset=UTF-8.
ibm-mq-rest-csrf-token: This header must be set, but the value can be anything, including being blank.
Authorization: This header must be sent if we are using basic authentication. For more information, see Use 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

The request body must be in JSON format in UTF-8 encoding. Within the request body attributes are defined, and named JSON objects are created to specify extra attributes. Any attributes that are not specified use the default value. These default values are as specified for the SYSTEM.DEFAULT queues on the queue manager. For example, a local queue inherits the values that are defined in SYSTEM.DEFAULT.LOCAL.QUEUE.

For example, the following JSON contains some attributes, and then the named JSON objects, events and storage. These named JSON objects define the extra attributes to create a local queue with queue depth high events enabled, and a maximum queue depth of 1000:

{
   "name": "queue1",
   "type": "local",
   "events" : {
      "depth" : {
          "highEnabled" : true,
          "highPercentage" : 75
    },
   "storage" : {
      "maximumDepth" : 1000
   }
}

For more examples, see examples.

The following attributes can be included in the request body:

name: Required.; String.; Specifies the name of the queue to create.

type

String.

Specifies the type of queue.

The value can be one of the following values:

local
alias
model
remote

The default value is local.

The following objects can be included in the request body to specify extra attributes:

remote: Contains attributes that are related to remote queues. The attributes in this object are supported only for remote queues.
alias: Contains attributes that are related to alias queues. The attributes in this object are supported only for alias queues.
model: Contains attributes that are related to model queues. The attributes in this object are supported only for model queues.
cluster: Contains attributes that are related to clusters.
trigger: Contains attributes that are related to triggering.
events: Contains two objects, one for queue depth and one for queue service interval events. Each object contains attributes that are related to the event type.
applicationDefaults: Contains attributes that are related to default behavior such as message persistence, message priority, shared input settings, and read ahead settings.
queueSharingGroup: Contains attributes that are related to queue sharing groups on z/OS.
dataCollection: Contains attributes that are related to data collection, monitoring, and statistics.
storage: Contains attributes that are related to message storage, such as the maximum depth of the queue, and the maximum length of messages that are allowed on the queue.
general: Contains attributes that are related to general queue properties, such as whether get or put operations are inhibited, the description of the queue, and transmission queue settings.
extended: Contains attributes that are related to extended queue properties, such as backout queue settings, and shared input settings.

For more information, see Request body attributes for queues.

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.

If token based security is used, the LTPA token that is used to authenticate the user must be provided with the request as a cookie. For more information about token-based authentication, see Use token-based authentication with the REST API.

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

If the like optional query parameter is not specified:
- For the queue that is specified by the name attribute in the request body, authority to issue the MQCMD_CREATE_Q PCF command must be granted.
- For the relevant SYSTEM.DEFAULT.*.QUEUE, authority to issue the MQCMD_INQUIRE_Q PCF command must be granted.
If the like optional query parameter is specified:
- For the queue that is specified by the name attribute in the request body, authority to issue the MQCMD_COPY_Q PCF command must be granted.
- For the queue that is specified by the like optional query parameter, authority to issue the MQCMD_INQUIRE_Q PCF command must be granted.

On UNIX, Linux, and Windows, we can grant authority to security principals to use IBM MQ resources by using the setmqaut command. For more information, see setmqaut (grant or revoke authority).

On z/OS, see Set up security on z/OS.

Response status codes

201: Queue created successfully.
400: Invalid data provided.; For example, invalid queue data is specified.
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.
500: Server issue or error code from IBM MQ.
503: Queue manager not running.

Response headers

The following headers are returned with the response:

location

If the request was successful, this header specifies the URL for the new queue.

If the optional query parameter commandScope=* is used, the URL that is returned is the URL for the local copy of the queue. If the optional query parameter commandScope=qmgrName is used, the URL that is returned is a partial URL that does not include information about the host and port.

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 created successfully. If an error occurs, the response body contains an error message. For more information, see REST API error handling.

Examples

The following example creates a local queue called localQueue. The following URL is used with the HTTP POST method:
```
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue/
```
The following JSON payload is sent:
```
{
   "name": "localQueue"
}
```

The following example creates a remote queue called remoteQueue. The following URL is used with the HTTP POST method:

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

The following JSON payload is sent:

{
   "name": "remoteQueue",
   "type": "remote",
   "remote" : {
      "queueName": "localQueue",
      "qmgrName": "QM2"
    }
}

The following example creates an alias queue called aliasQueue. The following URL is used with the HTTP POST method:

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

The following JSON payload is sent:

{
   "name": "aliasQueue",
   "type": "alias",
   "alias" : {
      "targetName": "localQueue"
   }
}

The following example creates a model queue called modelQueue. The following URL is used with the HTTP POST method:

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

The following JSON payload is sent:

{
   "name": "modelQueue",
   "type": "model",
   "model": {
       "type": "permanentDynamic"
    }
 }

The following example creates a clustered remote queue that is called remoteQueue1. The following URL is used with the HTTP POST method:

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

The following JSON payload is sent:

{
   "name": "remoteQueue1",
   "type": "remote",
   "remote" : {
      "queueName": "aLocalQueue1",
      "qmgrName" : "QM2",
      "transmissionQueueName": "MY.XMITQ"
   },
   "general" : {
         "description" : "My clustered remote queue"
   },
   "cluster" : {
      "name": "Cluster1",
      "workloadPriority": 9
   }
 }

The following example creates a clustered remote queue, remoteQueue2, based on another queue, remoteQueue1. All the attributes from remoteQueue1 are used, except for the queue name and the remote queue name. The following URL is used with the HTTP POST method:
```
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue/?like=remoteQueue1
```
The following JSON payload is sent:
```
{
   "name": "remoteQueue2",
   "type": "remote",
   "remote": {
      "queueName": "aLocalQueue2" 
   }
 }
```

Request body attributes for queues
When you create the request body for creating or modifying a queue with the administrative REST API, we can specify attributes for the queue within named JSON objects. A number of objects and attributes are available.

Parent topic: /admin/qmgr/{qmgrName}/queue