Service types

The IBM® MQ service provider exposes IBM MQ queues and topics, and the applications that are behind them, as services.

Services can be one-way or two-way and are created by using the API toolkit. For more information, see Build a service archive with the build toolkit. After a service is created using the API toolkit, the build toolkit can then be used to create this service for use in a DevOps workflow environment.

Services can be created by one of the following methods:
  1. Use the API toolkit. This method is preferred, because it provides enhanced capabilities such as enabling MQ messages to be greater than 32K. When a service is created with the API toolkit, it can later be built by the build toolkit. For more information, see Build a service archive with the build toolkit.
  2. Manually create a properties file that describes the service. The properties file is then used by the build toolkit to create the service.
  3. Configure the zosConnectService and mqService elements in the server.xml file. This method is supported only for compatibility with the IBM MQ service provider that was supplied with IBM MQ. If you use services that were created with this method, consider migrating them to use the API toolkit method.
One-way service
A one-way service can be used to provide a RESTful API for a single IBM MQ queue or topic and supports the sending of messages to either a queue or a topic, or receiving messages from a queue.
Figure 1. One-way service
This image is described in the surrounding text.

One-way services for sending messages can be created in the API toolkit by creating a service project of type MQ One-Way Service for Sending Messages, or by using a properties file with a messagingAction value of mqput. When a RESTful client sends an HTTP request with a JSON payload to a service of this type, the service sends a message with the payload as the message body, to the target queue or topic.

One-way services for receiving messages can be created in the API toolkit by creating a service project of type MQ One-Way Service for Receiving Messages, or by using a properties file with a messagingAction value of mqget. When a RESTful client sends an HTTP request with no payload to a service of this type, the service attempts to destructively get an available message from an IBM MQ queue. If a message was available, the payload of the message is returned as the response body of the HTTP request.

Two-way service
A two-way service allows a RESTful client to perform request-reply messaging on a pair of queues.
Figure 2. Two-way service
This image is described in the surrounding text.

The client sends an HTTP request, specifying a JSON payload. The service takes the payload, optionally converts it to a different format such as a COBOL copybook, and sends it as a message to a request queue.

A backend application gets the message, processes it and generates a response, which is placed on a reply queue. The service locates this message, takes its payload, optionally converts it to JSON and returns it as the response body of the HTTP request.

Note: This description of services that are configured by using service archive files is the best method. Services that are configured in the zosConnectService and mqService elements of the server.xml file work slightly differently.

Use services that are defined by the zosConnectService and mqService elements only when you migrate from the service provider that was supplied with IBM MQ. For more information, see Migrating a service to the IBM MQ service provider in IBM z/OS Connect.

The mqService element doesn't support the messagingAction element. Instead, callers of the service specify what action to take on the underlying IBM MQ resources by using the HTTP verb. For example,
  • For one-way services, an HTTP POST sends a message to an IBM MQ queue or topic, the equivalent of a messagingAction of mqput. An HTTP GET browses the first message from an IBM MQ queue. There is no messagingAction equivalent. An HTTP DELETE destructively gets a message from an IBM MQ queue, the equivalent of a messagingAction of mqget.
  • For two-way services, only the HTTP POST verb can be used.