IBM MQ REST administration brings queue manager configuration to the same toolbox as cloud microservices: HTTP verbs, JSON bodies, curl one-liners, and OpenAPI specifications checked into repositories. Where runmqsc requires shell access on a bastion and PCF requires Java or .NET client code, REST allows a Kubernetes operator or Ansible playbook running anywhere authorized to PATCH a channel attribute or GET queue depth attributes without installing the full MQ client toolkit on that runner—subject to network, TLS, and identity policies. Beginners encounter REST in IBM MQ on Cloud, Cloud Pak for Integration, and modern on-prem queue managers with mqweb enabled. This tutorial separates admin REST from messaging REST, describes typical URL patterns and verbs at a conceptual level, authentication models, comparison with MQSC and PCF, automation examples, security hardening, rate and performance limits, and troubleshooting 401, 403, and connection errors without duplicating release-specific path strings that change between versions—always verify paths in your IBM documentation.
Application teams may use IBM MQ messaging REST to publish and consume messages from languages without MQI. Administrators use REST admin to DEFINE-like operations and inquiries. Mixing the two in documentation causes security incidents—opening admin REST to the internet is not the same as exposing a put-only messaging endpoint. Network segmentation and API gateways should separate admin URLs from application traffic. Monitoring should tag admin calls for audit.
| Style | Transport | Typical user |
|---|---|---|
| MQSC / runmqsc | Text to command server | Mainframe/distributed ops |
| PCF | Binary admin messages | Explorer, Java monitors |
| REST admin | HTTPS JSON | Cloud pipelines, curl, operators |
On many deployments the mqweb server or embedded HTTP stack terminates TLS, authenticates the caller, and translates REST requests into internal administrative operations on the queue manager. The queue manager must be running; REST is not a substitute for strmqm. High availability setups place load balancers in front of multiple mqweb instances with consistent trust stores. Certificate renewal applies to admin URLs as well as application channels—expired HTTPS cert blocks Sunday-morning automation.
123456# Illustrative curl patterns — URLs vary by release and product # Replace host, port, qmgr name, and credentials per your environment curl -u admin:password https://mqhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue/PAYMENT.IN curl -X POST -H "Content-Type: application/json" \ -d '{"name":"DEMO.IN","type":"qlocal","maxDepth":5000}' \ https://mqhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue
GET retrieves object state or lists collections with paging on supported APIs. POST creates objects. PATCH or PUT updates attributes depending on API design for your release. DELETE removes definitions. Action endpoints may POST start-channel style operations. Idempotent automation favors understanding whether POST create fails on duplicate and whether PATCH is partial update—read IBM OpenAPI for your version. Pipelines should parse HTTP status codes: 201 created, 204 no content, 400 bad request, 403 forbidden, 404 not found.
TLS encrypts the connection. Credentials may be HTTP basic against a defined user, bearer tokens from corporate IdP on Cloud Pak, or platform service accounts. Behind the scenes the REST layer acts as an administrative identity subject to OAM and CONNAUTH like runmqsc. Least privilege service accounts should only alter objects in their namespace. Never embed production passwords in GitHub Actions without secret managers. Rotate credentials when staff leave.
REST admin is adjusting the queue manager settings through a secure website API instead of typing in a terminal—the website still asks the same command server brain inside the queue manager.
IBM publishes OpenAPI documents for REST admin on supported releases. Generate typed clients in Go, Java, or TypeScript for fewer URL typos than raw curl. Version-pin clients to queue manager version. Integration tests against containerized queue managers catch breaking API changes before production promotion.
Bulk inventory via REST may be slower than optimized PCF programs or parallel runmqsc. Rate-limit aggressive CI jobs. Command server contention affects all admin interfaces—schedule heavy REST deploys outside peak batch. Some attributes may lag Explorer support—verify parity before committing to REST-only operations.
401 unauthorized — wrong password or token expired. 403 forbidden — authenticated but OAM denies. Connection refused — mqweb down or wrong port. SSL handshake failure — trust store or SNI hostname mismatch. Empty response body — check Content-Type and API version prefix in URL. Compare same operation in runmqsc to isolate REST layer versus authority.
REST admin is asking the queue manager to change settings using web links and JSON instead of typing commands in a black window.
Document your site REST base URL, auth method, and one GET example from IBM docs.
List objects you still change only with MQSC because REST lacks an attribute.
Design network rules allowing CI server to admin REST but not application VLAN.
1. REST admin manages:
2. REST versus messaging REST:
3. curl GET on queue URL returns:
4. Production REST should use: