GET
Use the HTTP GET method with the subscription
resource to request information about subscriptions.
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
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.
- subscriptionName
- Optionally specifies the name of a subscription that exists on the specified queue manager.
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={object,...|*|object.attributeName,...}
-
- object,...
- Specifies a comma-separated list of JSON objects that contain related subscription attributes to return.
- *
- Specifies all attributes.
- object.attributeName,...
- Specifies a comma-separated list of queue configuration attributes to return.
- filter=filterValue
- Specifies a filter for the subscription definitions that are returned.
- id=id
- Specifies the ID of a subscription that exists on the queue manager specified.
- name=name
- Specifies a wildcard subscription name to filter on.
Request headers
- Authorization
- This header must be sent if you are using basic authentication. For more information, see Using HTTP basic authentication with the REST API.
- 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 Using token-based authentication with the REST API.
- 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.
On UNIX, 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
- 200
- Subscriptions retrieved successfully.
- 400
- Invalid data provided.
- 401
- Not authenticated.
- 403
- Not authorized.
- 404
- Subscription does not exist.
- 500
- Server issue or error code from IBM MQ.
- 503
- Queue manager not running.
Response headers
- 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 calledsubscription
. 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
- name
- String
- resolvedTopicString
- String
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.
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
{ "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
{ "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" } }] }