The IBM MQ REST messaging API lets applications put and get messages without compiling against MQI. A microservice can POST JSON to a queue on a queue manager reachable through mqweb, and a serverless function can GET the next message for light processing—provided TLS, authentication, and authority are configured. Beginners confuse messaging URLs with admin URLs and receive 404 or 403 while runmqsc works fine. This tutorial explains messaging versus admin REST, typical URL structure on modern releases, JSON message layout, put and get semantics compared to MQPUT and MQGET, syncpoint considerations, browsing, limits, and when REST messaging is the right integration choice.
Administration REST creates queues, displays channels, pings connections—object lifecycle. Messaging REST carries business payloads—the orders, payments, and events your enterprise routes through MQ. Both may run on the same mqweb port (often 9443) but paths and permissions differ. Grant messaging users +put and +get on specific queues, not +all admin on the queue manager unless they truly operate the estate.
| Aspect | REST messaging | MQI client |
|---|---|---|
| Transport | HTTPS JSON | TCP MQ protocol |
| Performance | Moderate overhead | Highest throughput |
| Deployment | Any HTTP stack | Needs MQ client install |
| Transactions | Per request model | Full UOW/syncpoint |
Client obtains token or basic auth credentials permitted on mqweb. TLS connects to https://host:9443/ibmmq/rest/v1/ (exact path per release—verify IBM doc). POST to the messaging endpoint for a named queue manager and queue with JSON containing message body (often base64 for binary), format, persistence, and optional headers. Success returns HTTP 201 or 200 with message identifiers. Failure returns 4xx with JSON error explaining authority or unknown queue—map to 2035 and 2085 familiar reason concepts.
12345# Illustrative curl—adjust URL and auth to your mqweb config: curl -k -u admin:password -X POST \ 'https://mqhost:9443/ibmmq/rest/v1/messaging/qmgr/QM1/queue/PAY.IN/message' \ -H 'Content-Type: application/json' \ -d '{"type":"string","message":"payment-12345","persistence":"persistent"}'
GET retrieves messages from a queue—destructive get removes the message like MQGET; browse endpoints may exist for non-destructive inspection per release. Specify wait interval in query parameters where supported to avoid tight polling loops that load mqweb. Long polling or moving to event-driven patterns (MQIPT, AMQP, or native MQI) may suit high fan-out consumers better than hammering REST GET every second.
REST maps MQMD concepts into JSON fields: format, priority, persistence, reply-to queue, correlation id. Beginners omit persistence and wonder why messages disappear on restart—set persistence explicitly for business-critical data. Character sets and CCSID matter for international text—test Unicode payloads end-to-end.
Choose REST when the team only has HTTP tooling, volume is moderate, and latency in tens of milliseconds is acceptable. Avoid REST as the core of mainframe-grade throughput on the same QM without load testing. Hybrid designs use REST at the edge and MQI inside the data center.
MQI is handing a letter directly to the postal clerk. REST messaging is filling a web form that the clerk transcribes onto a letter—convenient for remote submitters, slower for millions of letters.
Instead of using the special mail-machine language, you send a note through a website and the website puts the note in the right mailbox.
Lab: one REST put and one GET; verify CURDEPTH and message content in Explorer.
Compare latency: 1000 REST puts vs MQI puts in test (document hardware).
List three fields your JSON put must set for persistent payment messages.
1. REST messaging API moves:
2. Payload format is typically:
3. mqweb serves:
4. High throughput usually prefers: