REST API

From IBM MQ 9.0 onward, HTTP has joined MQSC and PCF as a first-class way to talk to a queue manager. The REST API runs inside the mqweb server—built on WebSphere Liberty—and gives developers, operators, and automation tools a familiar request/response model: JSON bodies, standard verbs, and TLS on port 9443 in typical installs. You can define a queue, inspect channel status, or put a test message without installing the full MQI client on a laptop. That does not replace decades of MQI and JMS for high-volume transactional paths; it complements them for cloud-native glue, CI/CD pipelines, and quick diagnostics. Beginners often confuse the IBM MQ Console in the browser with “the REST API”—they share mqweb, but the API is what scripts call. This tutorial explains administrative versus messaging endpoints, URL structure, authentication expectations, how REST relates to SVRCONN security, performance and design limits, and when your team should choose REST over a language client.

mqweb: The Server Behind the API

The queue manager process (amqzmgr) owns queues and channels; mqweb is a separate Java-based web server that holds REST and console applications. On many Linux installs you enable the optional web server component during installation or start it with platform-specific commands documented for your fix pack. mqweb reads configuration such as mqwebuser.xml and Liberty server.xml fragments to set HTTPS ports, authentication mechanisms, and which queue managers are registered for remote administration. If mqweb is down, REST returns connection errors even when runmqsc still works locally—two different entry points into the same logical queue manager data.

Administrative REST Versus Messaging REST

Administrative REST maps HTTP operations to object management similar to MQSC and PCF: list queues, create a channel definition, change a listener port. Automation teams store curl or Python requests in Git beside Terraform and Ansible. Messaging REST focuses on application data: POST a JSON or text payload to a queue name, GET to browse without removing (depending on API version and parameters), optionally correlate with request/reply patterns using documented headers. Mixing the two in one microservice is common—health checks use admin APIs while business events use messaging APIs—but grant least privilege: a deploy pipeline should not receive messaging put authority on production payment queues if it only defines test objects.

URL Construction and Encoding

REST paths are case-sensitive. Queue manager name QM1 and queue PAYMENTS.IN must appear exactly as defined. Characters such as slash, period, or percent in object names require URL encoding—IBM documents percent-encoding for question mark, period, forward slash, and percent itself. A mistake here produces 404-style errors that look like missing objects when the real issue is a malformed URL. Always test with DISPLAY QLOCAL in runmqsc first to copy the precise name string.

1
2
3
4
5
6
7
8
9
10
11
12
13
# Illustrative messaging PUT (replace host, port, credentials, names)
curl -k -X POST \
  'https://mqhost.example.com:9443/ibmmq/rest/v1/messaging/qmgr/QM1/queue/DEV.QUEUE.1/message' \
  -H 'Content-Type: application/json' \
  -H 'ibm-mq-rest-csrf-token: 1' \
  -u 'appuser:secret' \
  -d '{"type":"string","message":"Hello from REST"}'
 
# Browse (GET) — does not remove message per v1 browse semantics; verify your release
curl -k -X GET \
  'https://mqhost.example.com:9443/ibmmq/rest/v1/messaging/qmgr/QM1/queue/DEV.QUEUE.1/message' \
  -H 'ibm-mq-rest-csrf-token: 1' \
  -u 'appuser:secret'

The ibm-mq-rest-csrf-token header is required for mutating requests in default mqweb security configurations—it prevents cross-site request forgery when browsers are involved; scripts must send it too. Content-Type and message body format must match supported types (often string/JSON mappings to MQSTR). Binary payloads use documented binary modes in newer API versions—read the IBM page for your exact fix pack before production.

Authentication and Authorization

mqweb authenticates the HTTP user separately from how MQI maps SVRCONN MCAUSER. Common patterns include basic authentication against a registry configured in Liberty, LDAP, or client certificate TLS at the HTTP layer. After authentication, the queue manager still enforces OAM (or RACF on z/OS) for puts and admin operations—the REST user must be granted +connect, +put, +get, or +dsp as needed. A successful TLS handshake to port 9443 does not mean the PUT succeeds; watch for 2035-equivalent HTTP responses. Align REST service accounts with the same least-privilege IDs you would use for an application SVRCONN.

• Configure mqweb user registry or LDAP realm in Liberty config.
• Grant queue manager authority to the authenticated ID (or mapped MCAUSER).
• Use TLS for production; disable insecure -k curl only in lab.
• Rotate passwords and certificates on the same calendar as channel certs.

Explainer: REST as a Reception Desk

Think of MQI as walking into the factory floor with a badge that lets you place crates directly on conveyor belts. REST is asking the reception desk to accept a parcel and log it—the desk clerk (mqweb) translates your form into the internal process. The parcel still ends on the same queue, but you follow HTTP rules at the door. High-volume shipping still uses the factory floor badge; occasional courier drops use the desk.

When to Choose REST Versus Language Clients

1. Choose REST for quick integration, Kubernetes probes, serverless functions, and teams without MQ client libraries installed.
2. Choose MQI/JMS/.NET for sustained high throughput, syncpoint-heavy transactions, and complex MQMD control.
3. Choose REST for admin automation if PCF is unavailable but HTTP is allowed from your pipeline network zone.
4. Avoid REST as the sole path for large binary payloads unless you validate size limits and encoding for your release.

Latency is higher than a persistent TCP SVRCONN because each operation is request/response HTTP. Connection pooling in your HTTP client mitigates setup cost but does not match a long-lived MQCONN for burst traffic. Measure before rewriting a COBOL bridge that already does thousands of syncpointed puts per second.

Installation and Operations

Ensure the web server component is installed and started. Verify https://host:9443/ibmmq/console/ loads (after accepting corporate CA or installing trust). Register queue managers for remote console/REST if using a central mqweb instance. Monitor mqweb logs separately from AMQERR01—TLS and Liberty misconfiguration show up early in web server traces. From IBM MQ 9.3.5 onward, a stand-alone IBM MQ Web Server option exists on Linux for some topologies; check whether your estate uses embedded or stand-alone mqweb before writing runbooks.

Versioning: v1, v2, and v3 Messaging APIs

IBM added messaging REST v2 and v3 for improved semantics (for example destructive get options and richer message properties in later releases). New projects should read the latest documented version for their queue manager level and pin URLs in code—do not assume v1 behavior on a v3 endpoint. Admin REST similarly evolves; automation should assert HTTP status and error JSON bodies rather than parsing HTML error pages.

Troubleshooting REST Failures

• Connection refused — mqweb not running or firewall on 9443.
• 401/403 — authentication or CSRF token missing on POST.
• 404 — wrong URL case or unencoded special character in queue name.
• 500 with MQ reason — authorized user lacks put/browse; check OAM and queue DEFPSIST.
• TLS errors — trust store on client does not include mqweb certificate CA.

Explain Like I'm Five: REST API

REST is like mailing a letter to the mailroom window instead of walking into the sorting room yourself—you fill out a form on the window (HTTP), and the mailroom worker puts the letter in the right box (queue).

Practice Exercises

Exercise 1

Write a curl POST that puts the text Order-1001 to DEV.QUEUE.1 on QM1. List headers you need besides Content-Type.

Exercise 2

Your PUT returns 403 but runmqsc PUT works as mqm. List three authority checks specific to REST.

Exercise 3

Compare one REST PUT versus one Java JMS send for a 10,000-message soak test—what metrics would you capture?

Frequently Asked Questions

Test Your Knowledge