POST
We can use the HTTP POST method with the /messaging/qmgr/{qmgrName}/topic/{topicString}/message resource to publish messages to the specified topic on the specified queue manager.
Publishes a text-based message in the HTTP request body to the specified queue manager and topic. The queue manager must be on the same machine as the mqweb server, and only text-based messages are supported. Messages are published as MQSTR formatted messages using the current user context, and have a default message priority of 4.
- Resource URL
- Request headers
- Request body format
- Security requirements
- Response status codes
- Response headers
- Response body format
- Examples
Resource URL
https://host:port/ibmmq/rest/v2/messaging/qmgr/{qmgrName}/topic/{topicString}/message
- qmgrName
- Specifies the name of the queue manager to connect to for messaging. The queue manager must be on the same machine as the mqweb server.
- topicString
- Specifies the topic string on which to publish the message.
We can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configure HTTP and HTTPS ports.
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.
- Content-Type
- This header must be sent with one of the following values:
- text/plain;charset=utf-8
- text/html;charset=utf-8
- text/xml;charset=utf-8
- application/json;charset=utf-8
- application/xml;charset=utf-8
- ibm-mq-rest-csrf-token
- This header must be set, but the value can be anything, including being blank.
The following headers can optionally be sent with the request:
- Accept-Language
- This header specifies the required language for any exceptions or error messages returned in the response message body.
- ibm-mq-md-expiry
- This header sets the expiry duration for the created message. The expiry of a message starts
from the time the message arrives at the queue manager. As a result network latency is ignored. The
header must be specified as one of the following values:
- unlimited
- The message does not expire.
- Integer value
- Milliseconds before message expiry.
- ibm-mq-md-persistence
- This header sets the persistence for the created message. The header must be specified as one of
the following values:
- nonPersistent
- The message does not survive system failures or queue manager restarts.
- persistent
- The message survives system failures or queue manager restarts.
- ibm-mq-md-replyTo
- This header sets the reply-to destination for the created message. The format of the header uses the standard notation of supplying the reply-to queue and an optional queue manager: replyQueue[@replyQmgr]
Request body format
The request body must be text and use UTF-8 encoding. No specific text structure is required. An MQSTR formatted message containing the request body text is created and published to the specified topic.
For more information, see examples.
Note:Newlines in incoming strings are removed by the HTTP POST operation. REST applications should not use newlines in messages that are sent or published using the REST API, as they will be lost.
Security requirements
The caller must be authenticated to the mqweb server. The MQWebAdmin and MQWebAdminRO roles are not applicable for the messaging REST API. For more information about security for the REST API, see IBM MQ Console and REST API security.
Once authenticated to the mqweb server the user is capable of using both the messaging REST API and the administrative REST API.
The security principal of the caller must be granted the ability to publish messages to the specified topic:- The topic that is specified by the {topicString} portion of the resource URL must be PUBLISH enabled.
For the topic that is specified by the {topicString}
portion of the resource URL, +PUB authority must be granted to the security
principal of the caller.
- For the topic that is specified by the {topicString} portion of the resource URL, UPDATE access must be granted to the security principal of the caller.
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.
If we use Advanced Message Security (AMS) with the messaging REST API, note that all messages are encrypted by using the context of the mqweb server, not the context of the user that posts the message.
Response status codes
- 201
- Message created and published successfully.
- 400
- Invalid data provided.
- 401
- Not authenticated.
- 403
- Not authorized.
- 404
- Queue manager does not exist.
- 405
- Topic is PUBLISH inhibited.
- 415
- A message header or body is an unsupported media type.
- 500
- Server issue or error code from IBM MQ.
- 502
- The current security principal cannot publish the message as the messaging provider does not support the required function. For example, if the mqweb server class path is invalid.
- 503
- Queue manager not running.
Response headers
The following headers are returned with the response:
- Content-Language
- Specifies the language identifier of the response message in the event of any errors or exceptions. Used in conjunction with Accept-Language request header to indicate the required language for any error or exception conditions. The mqweb server default is used if the requested language is unsupported.
- Content-Length
- Specifies the length of the HTTP response body, even when there is no content. Upon success the value is zero.
- Content-Type
- Specifies the type of response body. Upon success the value is text/plain;charset=utf-8. In the event of any errors or exceptions, the value is application/json;charset=utf-8.
Response body format
The response body is empty if the message is published successfully. If an error occurs, the response body contains an error message. For more information, see REST API error handling.
Examples
The following example logs in a user called mquser with the password mquser. In cURL, the log in request might look like the following Windows example. The LTPA token is stored in the cookiejar.txt file by using the -c flag:curl -k "https://localhost:9443/ibmmq/rest/v1/login" -X POST
-H "Content-Type: application/json" --data "{\"username\":\"mquser\",\"password\":\"mquser\"}"
-c c:\cookiejar.txt
After the user is logged in, the LTPA token and ibm-mq-rest-csrf-token HTTP header are used to authenticate further requests. The ibm-mq-rest-csrf-token token_value can be any value, including blank.
- The following Windows cURL example publishes a
message to the topic string myTopic on queue manager QM1, using
default options. The message contains the text "Hello World!":
curl -k "https://localhost:9443/ibmmq/rest/v2/messaging/qmgr/QM1/topic/myTopic/message" -X POST -b c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: token_value" -H "Content-Type: text/plain;charset=utf-8" --data "Hello World!"
- The following Windows cURL example publishes a
persistent message to the topic string myTopic/thisTopic on queue manager
QM1, with an expiry of 2 minutes. The message contains the text "Hello
World!":
curl -k "https://localhost:9443/ibmmq/rest/v2/messaging/qmgr/QM1/topic/myTopic%2FthisTopic/message" -X POST -b c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: token_value" -H "Content-Type: text/plain;charset=utf-8" -H "ibm-mq-md-persistence: persistent" -H "ibm-mq-md-expiry: 120000" --data "Hello World!"
Parent topic: /messaging/qmgr/{qmgrName}/topic/{topicString}/message