HTTP considerations for the IBM MQ service provider

When you use the IBM® MQ service provider, be aware of the following HTTP-related information.

HTTP verbs

zosConnect-2.0 Applies to zosConnect-2.0.

The IBM MQ service provider that is included as part of IBM MQ has a hardcoded mapping of HTTP verbs to messaging operations. These hardcoded mappings made it difficult to build truly RESTful APIs.

The IBM MQ service provider that is included with IBM z/OS® Connect does not have these hardcoded mappings. Any HTTP verb can be used to invoke either a one-way or a two-way service.

For a one-way service, the actual operation that is performed on the underlying IBM MQ queue or topic depends on the service project type if the service was created in the API toolkit, or the messagingAction property if the service was created from a properties file. For more information, see Creating an IBM MQ service by using a properties file.

A service project type of MQ One-Way Service for Sending Messages, or a messagingAction of mqput allows a message to be sent to either a queue or a topic.

A service project type of MQ One-Way Service for Receiving Messages, or a messagingAction of mqget allows a message to be received from a queue.

HTTP payload considerations

For one-way services configured to send messages:

The HTTP request payload is optionally transformed by using the configured data transformation, and then sent as the payload of the IBM MQ message.
The minimum valid payload is {}, that is, an empty JSON object.
If the message is successfully sent, an empty HTTP response is returned to the caller with an HTTP status code of 204 (No Content).
If a failure occurs, a response is returned as described in the HTTP status codes section.

For one-way services configured to receive messages:

Any HTTP request payload is ignored.
If a message is available on the IBM MQ queue, the payload of the message is optionally transformed by using the configured data transformation and then returned as the HTTP response body. The HTTP status code is 200 (OK).
If the message has no payload, the HTTP response body is empty and the HTTP status code is 200 (OK).
If no message is available on the IBM MQ queue, the HTTP response body is empty and the HTTP status code is 204 (No Content).

For two-way services:

The HTTP request payload is optionally transformed by using the configured data transformation, and then sent as the payload of the IBM MQ message to the request queue or topic.
The minimum valid payload is {}, that is, an empty JSON object.
If a message is available on the IBM MQ reply queue, the payload of the message is optionally transformed by using the configured data transformation and then returned as the HTTP response body, the HTTP status code is 200 (OK).
If the message on the reply queue has no payload, the HTTP response body is empty, and the HTTP status code is 200 (OK).
If no message is available on the IBM MQ reply queue, the HTTP response body is empty, and the HTTP status code is 204 (No Content).

HTTP headers

When a non-blank HTTP request body is sent to either a one-way or a two-way service, it must be a valid JSON object encoded in UTF-8. The Content-Type=application/json HTTP header must also be specified.

Several optional HTTP headers can also be specified to adjust the behavior of the IBM MQ service provider. For more information about the HTTP headers that can be used with the IBM MQ Service Provider, see HTTP headers that can be used with the IBM MQ service provider.

HTTP status codes

If the IBM MQ service provider detects an error, the service sets an HTTP status code in the range of 400-599. Otherwise, the status codes that were 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.

In some cases, an exception stack trace in JSON format is returned to the caller as shown in the server-side example.

Server-side error

If the IBM MQ service provider experiences an unexpected error, then the stack trace is turned into JSON format, and returned to the caller with an HTTP status code of 500 (Internal Server Error). Suitable diagnostics are also be written to the IBM z/OS Connect logs.

A sample error response payload is shown in Figure 1:

Figure 1. A simplified example of an error response payload

{
"errorText":"BAQM0006E: An unexpected JMSException occurred while processing a request for service 'mq7'."
  "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>
       ]
     }
   ]
  }
}