Verbs the MQ Service Provider supports

The MQ Service Provider supports the HTTP GET, HTTP DELETE, and HTTP POST verbs as used in the IBM MQ Bridge for HTTP, with the same meaning. Use of these verbs permits basic interaction with IBM MQ for z/OS®, and composition of a number of these verbs allows more complicated functions to be exposed.

When doing an HTTP GET or HTTP DELETE the MQ Service Provider ignores any body provided in the request.

If the HTTP GET or HTTP DELETE is successful:

  • The message payload is returned in the HTTP response body, and the HTTP status code is 200.
  • A message with no payload is returned with no HTTP body. If there is no message available, no HTTP body is returned and the HTTP status code is 204 (No Content).
Attention: z/OS Connect expects JSON payloads to always be in object form; that is, the minimal valid payload is {}.

When doing an HTTP POST, the only expected parameters are the message payload, which will be in the HTTP body, and the various elements described in mqzOSConnectService element.

If the POST is successful a:

    One-way service
    Returns an HTTP 204 (No Content) code together with an empty payload.

    Two-way service
    Returns either the contents of the reply message in JSON format, or, if no reply message was available, an empty response body with an HTTP response code of 204 (No Content).


HTTP headers

When issuing an HTTP POST, to either a one-way or a two-way service, the HTTP body must be a valid JSON object. You must specify:

  • A Content-Type=application/json HTTP header to the HTTP_POST
  • An encoding of UTF-8

A number of optional HTTP headers can also be specified, depending on the HTTP verb used, to adjust the behavior of the MQ Service Provider. See HTTP headers that can be used with the MQ Service Provider for more details.


HTTP codes

If the MQ Service Provider detects an error, the service sets an HTTP status code in the range of 400-599. Otherwise, the status codes documented previously are always returned.

    Client side error
    If non valid data is passed in by the calling application, an HTTP status code in the range 400-499 is returned to the caller. The exact status code depends on the error.
    If the non valid data was detected by an exception being thrown, then a stack trace in JSON format is provided as in the server side example.

    Server side error
    If the MQ Service Provider experiences an unexpected error then the stack trace will be turned into JSON format, and returned to the caller with an HTTP status code of 500 (Internal Server Error). Suitable diagnostics will also be written to the z/OS Connect logs.
    A simplified example error response payload is:
    {
"errorText":"CSQZ0006E: An unexpected JMSException occurred while processing a request 
for the 'mq7' service. ",
  "exceptionData":{
    "exceptions":[
   {   
     "stackTrace":[
       "com.ibm.msg.client.jms.DetailedInvalidDestinationException: JMSWMQ2008: 
Failed to open MQ queue 'ThisQueueDoesNotExist'.",
<further content removed for brevity>
      ]
    },
     {
      "stackTrace":[
       "com.ibm.mq.MQException: JMSCMQ0001: WebSphere MQ call failed with 
compcode '2' ('MQCC_FAILED') reason '2085' ('MQRC_UNKNOWN_OBJECT_NAME').",
<further content removed for brevity>
       ]
   ]
  }
}