GET

Resource URL

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

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

attributes={extended|*|extended.attributeName,...}

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

This parameter is not valid if you specify a remote queue manager in the resource URL.

extended

Specifies that all extended attributes are retrieved.

*

Specifies all attributes. This parameter is equivalent to extended.

extended.attributeName,...

Specifies a comma-separated list of extended attributes to return.

For example, to return the installationName attribute, specify extended.installationName.

For a full list of extended attributes, see Extended attributes for queue managers.

status={status|*|status.attributeName,...}

status

Specifies that all status attributes are returned.

*

Specifies all attributes. This parameter is equivalent to status.

status.attributeName,...

Specifies a comma-separated list of queue manager status attributes to return.

The queue manager must be running to return the status attributes.

For example, to return the connectionCount attribute, specify status.connectionCount.

For a full list of status attributes, see Status attributes for queue managers.

state=state

Specifies that only queue managers with the specified state are returned. The following values are valid values:

On all platforms:

• running
• ended

On AIX, Linux, and Windows:

• endedImmediately
• endedPreemptively
• endedUnexpectedly
• starting
• quiescing
• endingImmediately
• endingPreemptively
• beingDeleted
• stateNotAvailable
• runningAsStandby
• runningElsewhere

You can specify the state=state optional query parameter only if you do not specify a queue manager name within the resource URL. That is, you cannot request information about a specific queue manager in a specific state.

ha={*|ha|attributeName,…}

Specifies that HA information is returned for HA queue managers. You can specify that all HA attributes are returned (* or ha), or specify particular attributes (one or more of ha.type, ha.floatingIPAddress, and ha.floatingIPInterface). You can combine DR attributes with any other attributes of the qmgr resource.

If you specify this attribute on a platform other than IBM MQ Appliance, the response is bad request 400.

dr={*|dr|attributeName,…}

Specifies that DR information is returned for DR queue managers. You can specify that all DR attributes are returned (* or dr), or specify particular attributes (dr.replicationPort or dr.remoteIPAddress). You can combine DR attributes with any other attributes of the qmgr resource.

If you specify this attribute on a platform other than IBM MQ Appliance, the response is bad request 400.

nativeha={*|nativeha|attributeName,…}

Specifies that Native HA information is returned. You can specify that all Native HA attributes are returned (* or nativeha), or specify particular attributes (one of more of attributeName). You can combine Native HA attributes with any other attributes of the qmgr resource.

Request headers

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.

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 Using token-based authentication with the REST API.

On AIX, Linux, and Windows, you 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 Setting up security on z/OS.

Response status codes

Response headers

Response body format

The response is in JSON format in UTF-8 encoding. The response contains an outer JSON object that contains a single JSON array called qmgr. Each element in the array is a JSON object that represents information about a queue manager. Each JSON object contains the following attributes:

The following objects can be included in the JSON object that represents information about a queue manager. Which objects and attributes are returned depends on the URL that was specified for the request:

For more information, see Response body attributes for queue managers.

If an error occurs, the response body contains an error message. For more information, see REST API error handling.

Examples for AIX, Linux, and Windows

Examples for IBM MQ Appliance

• The following example gets HA information from all queue managers on the appliance. The following URL is used with the HTTP GET method:

  https://appliance.example.com:5554/ibmmq/rest/v3/admin/qmgr/?ha=*

  In the example configuration, there is one HA queue manager named HAQM1. The following JSON response is returned:

  {
    "qmgr": [
      {
        "name": "HAQM1",
        "ha": {
          "floatingIPAddress": "172.20.37.16",
          "floatingIPInterface": "eth22",
          "type": "replicated"
        },
        "state": "endedImmediately"
       }
    ]
  }

• The following example gets DR information from all queue managers on the appliance. The following URL is used with the HTTP GET method:

  https://appliance.example.com:5554/ibmmq/rest/v3/admin/qmgr/?dr=*

  In the example configuration, there is one DR queue manager named DRQM1. The following JSON response is returned:

  {
    "qmgr": [    
      {
        "name": "DRQM1",
        "state": "endedUnexpectedly",
        "dr": {
          "remoteIPAddress": [
            "172.20.39.0"
          ],
          "replicationPort": 1419
      }
    ]
  }

• The following example gets extended information about the queue manager QM1. The following URL is used with the HTTP GET method:

  https://appliance.example.com:5554/ibmmq/rest/v3/admin/qmgr/QM1?attributes=extended

  The following JSON response is returned:

  {
      "qmgr": [{
          "extended": {
             "installationName": "MQAppliance",
             "isDefaultQmgr": false,
             "encryptedFileSystem": "yes"
          },
          "name": "QM1",
          "state": "endedImmediately"
      }]
  }

Examples for z/OS