GET

Use the HTTP GET method with the subscription resource to request information about subscriptions.

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

The information that is returned is similar to the information returned by the Inquire Subscription PCF command, and the DISPLAY SUB MQSC command.

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}/subscription/{subscriptionName}

qmgrName

Specifies the name of the queue manager on which to query the subscriptions.

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.

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

subscriptionName

Optionally specifies the name of a subscription that exists on the specified queue manager.

The subscription name is case-sensitive.

If the subscription name includes any non-alphanumeric characters, they must be URL encoded.

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

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

object,...: Specifies a comma-separated list of JSON objects that contain related subscription attributes to return.; For example, to return all subscription attributes that are related to time stamps, specify timestamps. To return all subscription attributes that are related to the destination and user, specify destination,user.; We cannot specify the same object more than once.; For a full list of objects and associated attributes, see Attributes for subscriptions.
*: Specifies all attributes.
object.attributeName,...: Specifies a comma-separated list of queue configuration attributes to return.; Each attribute must specify the JSON object that contains the attribute, in the form object.attributeName. For example, to return the correlationId attribute, which is contained in the destination object, specify destination.correlationId.; We cannot specify the same attribute more than once.; For a full list of attributes and associated objects, see Attributes for subscriptions.

filter=filterValue

Specifies a filter for the subscription definitions that are returned.

This query parameter cannot be used if we specify a subscription name in the resource URL or if we use the ID query parameter.

We can specify only one filter.

filterValue has the following format:

attribute:operator:value

where:

attribute

Specifies one of the applicable attributes. For a full list of attributes, see Attributes for subscriptions. The following attributes cannot be specified:

name
id

To filter on any attributes that are time stamps, the filter can specify any portion of the time stamp, with a trailing asterisk, *. The format of a time stamp is, YYYY-MM-DDThh:mm:ss. For example, we can specify 2001-11-1* to filter on dates in the range 2001-11-10 to 2001-11-19, or 2001-11-12T14:* to filter any minute in the specified hour of the specified day.

Valid values for the YYYY section of the date are in the range 1900 - 9999.

The time stamp is a string. Therefore, only the equalTo and notEqualTo operators can be used with the time stamp.

operator

Specifies one of the following operators:

lessThan: Use this operator only with integer attributes.
greaterThan: Use this operator only with integer attributes.
equalTo: Use this operator with any attribute.
notEqualTo: Use this operator with any attribute.
lessThanOrEqualTo: Use this operator only with integer attributes.
greaterThanOrEqualTo: Use this operator only with integer attributes.

value

Specifies the constant value to test against the attribute.

The value type is determined by the attribute type.

For string and boolean attributes, we can omit the value field after the colon. For string attributes, omit the value to return subscriptions with no value for the specified attribute. For boolean attributes, omit the value to return any subscriptions that have the specified attribute set to false. For example, the following filter returns all subscriptions where the topic name attribute is not specified:

filter=topic.name:equalTo:

A single asterisk, *, can be used for string attributes specified at the end of the value as a wildcard.

If the value includes non-alphanumeric characters, then they must be URL encoded. If the value contains a percent character or any asterisk that is not intended to be a wildcard, then the value must be URL encoded a second time. That is, a percent character must be encoded as %2525. An asterisk must be encoded as %252A.

id=id

Specifies the ID of a subscription that exists on the queue manager specified.

This query parameter cannot be used if we specify a subscription name in the resource URL or the name query parameter.

The ID is a string that contains a hexadecimal number. It can be comprised of a mixture of uppercase and lowercase characters.

name=name

Specifies a wildcard subscription name to filter on.

This query parameter cannot be used if we specify a subscription name in the resource URL or the id query parameter.

The name specified must either be blank or include an asterisk, *, as a wildcard. We can specify one of the following combinations:

: Specifies that subscriptions that do have a blank name attribute are returned.
*: Specifies that all subscriptions are returned.
prefix*: Specifies that all subscriptions with the specified prefix in the subscription name are returned.
*suffix: Specified that all subscriptions with the specified suffix in the subscription name are returned.
prefix*suffix: Specifies that all subscriptions with the specified prefix and the specified suffix in the subscription name are returned.

Request headers

The following headers must be sent with the request:

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

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 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:

For the subscription that is specified by the {subscriptionName} portion of the resource URL, the id query parameter, or for subscriptions that match the specified query parameters, authority to issue the MQCMD_INQUIRE_SUBSCRIPTION PCF command must be granted.

A principal has display authority if the principal can issue the MQCMD_INQUIRE_SUBSCRIPTION PCF command. If the principal has display authority for only some of the subscriptions that are specified by the resource URL and query parameters, then the array of subscriptions that is returned from the REST request is limited to those subscriptions that the principal has authority to display. No information is returned about subscriptions that cannot be displayed. If the principal does not have display authority for any of the subscriptions that are specified by the resource URL and query parameters, an HTTP status code of 403 is returned.

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

200: Subscriptions retrieved successfully.
400: Invalid data provided.; For example, invalid subscription attributes 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. 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: Subscription 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:

Content-Type: This header is returned with a value of application/json;charset=utf-8.
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 is in JSON format in UTF-8 encoding. The response contains an outer JSON object that contains a single JSON array called subscription. Each element in the array is a JSON object that represents information about a subscription. Each of these JSON objects contains the following attributes:

id: Hexadecimal string; Specifies the unique key that identifies the subscription.; This attribute is always returned.
name: String; Specifies the name of the subscription.; This attribute is always returned.
resolvedTopicString: String; Specifies the fully resolved topic string using the combined values from the topic name and defined string when the subscription was created.; This attribute is always returned.

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

topic: Contains attributes that are related to a defined topic.
selector: Contains attributes that are related to the message selector.
destination: Contains attributes that are related to the destination queue / queue manager.
user: Contains attributes that are related to user, such as the accounting token, the user ID that owns the subscription and the user data.
general: Contains attributes that are related to general subscription properties, such whether the subscription is durable, how the subscription was created and whether wildcards should be interpreted in the topic string.
extended: Contains attributes that are related to extended subscription properties, such as the expiry time, the message priority, and the network scope.
timestamps: Contains attributes that are related to date and time information, such as the time stamp of when the subscription was created.

For more information, see Response body attributes for subscriptions.

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

Examples

The following example lists all subscriptions on the queue manager QM1. The following URL is used with the HTTP GET method:

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

The following JSON response is returned:

{
    "subscription":
    [{
        "id": "414D5120514D33202020202020202020A878195911AFD206",
        "name": "SYSTEM.DEFAULT.SUB",
        "resolvedTopicString": ""
    },
    {
        "id": "414D5120514D332020202020202020202C0740592162214A",
        "name": "MySubscription",
        "resolvedTopicString": "sports/golf"
    },
    {
        "id": "414D5120514D332020202020202020202C07405921621307",
        "name": "QM1 SYSTEM.BROKER.INTER.BROKER.COMMUNICATIONS 414D51590101000000000000000000000000000000000000 SYSTEM.BROKER.ADMIN.STREAM MQ/QM1 /StreamSupport",
        "resolvedTopicString": "SYSTEM.BROKER.ADMIN.STREAM/MQ/QM1 /StreamSupport"
    }]
}

The following example lists all subscriptions on the queue manager QM1, showing their topic properties. The following URL is used with the HTTP GET method:

https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/subscription?attributes=topic

The following JSON response is returned:

{
    "subscription":
    [{
        "id": "414D5120514D33202020202020202020A878195911AFD206",
        "name": "SYSTEM.DEFAULT.SUB",
        "resolvedTopicString": "",
        "topic": {
            "definedString": "",
            "name": ""
        }
    },
    {
        "id": "414D5120514D332020202020202020202C0740592162214A",
        "name": "MySubscription",
        "resolvedTopicString": "sports/snooker",
        "topic": {
            "definedString": "sports/snooker",
            "name": ""
        }
    },
    {
        "id": "414D5120514D332020202020202020202C07405921621307",
        "name": "QM1 SYSTEM.BROKER.INTER.BROKER.COMMUNICATIONS 414D51590101000000000000000000000000000000000000 SYSTEM.BROKER.ADMIN.STREAM MQ/QM1 /StreamSupport",
        "resolvedTopicString": "SYSTEM.BROKER.ADMIN.STREAM/MQ/QM1 /StreamSupport",
        "topic": {
            "definedString": "MQ/QM1 /StreamSupport",
            "name": "SYSTEM.BROKER.ADMIN.STREAM"
        }
    }]
}

Response body attributes for subscriptions
When we use the HTTP GET method with the subscription object to request information about subscriptions, the following attributes are returned within named JSON objects.

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