IBM MQ Bindings
This document defines how to describe IBM MQ specific information with AsyncAPI.
Version
Current version is 0.1.0.
Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this bindings specification are to be interpreted as described in IETF RFC2119.
AsyncAPI considerations
This specification binding requests that the AsyncAPI specification reserve the IBM MQ protocol to allow connections to queue manager endpoints to be defined within the server object.
URI scheme considerations
For the purposes of establishing an IBM MQ binding for use within AsyncAPI, this document defines the URI scheme ibmmq:// consisting of components and generic URI syntax as specified in RFC3986
Defining an IBM MQ queue manager endpoint in the server object url field
When defining an IBM MQ url for a queue manager endpoint, the ibmmq:// URI scheme MUST be used. IBM MQ URIs are defined using the following components.
URI query or fragment components MUST NOT be used within the ibmmq:// scheme. Path components that contain characters reserved by RFC2936 such as / MUST be percent encoded as defined in Section 2.2 of RFC2936. port MUST be specified as part of the authority component in the ibmmq:// scheme.
Defining IBM MQ queue manager endpoints with the AsyncAPI Server Object
This section defines the convention for how IBM MQ queue manager endpoints are encoded within the AsyncAPI Server Object fields. A groupId field has been made available on the IBM MQ AsyncAPI server binding object to allow server objects to be defined as a related collection. This is necessary to group, or cluster, IBM MQ queue manager endpoints within the AsyncAPI specification and where a Client Channel Definition Table (CCDT) reference is not appropriate.
Example of two possible MQ servers defined using ibmmq url syntax
1servers:
2 production1:
3 url: ibmmq://qmgr1host:1414/qm1/DEV.APP.SVRCONN
4 protocol: ibmmq
5 production2:
6 url: ibmmq://qmgr2host:1414/qm2/DEV.APP.SVRCONN
7 protocol: ibmmqExample of single MQ server defined using ibmmq url syntax and with no queue manager name specified
1servers:
2 production:
3 url: ibmmq://qmgr1host:1414//DEV.APP.SVRCONN
4 protocol: ibmmqDefining an IBM MQ queue manager endpoint CCDT in the url field
When defining a connection to IBM MQ, a CCDT connection file can be specified. The server url will specify the location of the file with additional information contained within the server binding to specify its usage.
Example using an IBM MQ CCDT file url
1servers:
2 production1:
3 url: 'http://my-ccdt-json-file'
4 protocol: ibmmq
5 production2:
6 url: 'file://myccdt.json'
7 protocol: ibmmqServer Binding Object
This object contains server connection information about the IBM MQ server, referred to as an IBM MQ queue manager. This object contains additional connectivity information not possible to represent within the core AsyncAPI specification.
Fixed Fields
| Field Name | Type | Description | Applicability [default] | Constraints |
|---|---|---|---|---|
groupId | string | Defines a logical group of IBM MQ server objects. This is necessary to specify multi-endpoint configurations used in high availability deployments. If omitted, the server object is not part of a group. | OPTIONAL | MUST NOT be specified for URI Scheme http:// or file:// |
ccdtQueueManagerName | string | The name of the IBM MQ queue manager to bind to in the CCDT file. | OPTIONAL [*] | MUST NOT be specified for URI Scheme ibmmq:// |
cipherSpec | string | The recommended cipher specification used to establish a TLS connection between the client and the IBM MQ queue manager. More information on SSL/TLS cipher specifications supported by IBM MQ can be found on this page in the IBM MQ Knowledge Center. | OPTIONAL [ANY] | MUST NOT be specified for protocol ibmmq or URI Scheme file:// or http:// |
multiEndpointServer | boolean | If multiEndpointServer is true then multiple connections can be workload balanced and applications should not make assumptions as to where messages are processed. Where message ordering, or affinity to specific message resources is necessary, a single endpoint (multiEndpointServer = false) may be required. | OPTIONAL [false] | MUST NOT be specified for URI Scheme file:// or http:// |
heartBeatInterval | integer | The recommended value (in seconds) for the heartbeat sent to the queue manager during periods of inactivity. A value of zero means that no heart beats are sent. A value of 1 means that the client will use the value defined by the queue manager. More information on heart beat interval can be found on this page in the IBM MQ Knowledge Center. | OPTIONAL [300] | MUST be 0-999999 |
bindingVersion | string | The version of this binding. | OPTIONAL [latest] | - |
This object MUST contain only the properties defined above.
Example for multiple endpoints defined in the AsyncAPI configuration
1servers:
2 production1:
3 url: ibmmq://qmgr1host:1414/qm1/DEV.APP.SVRCONN
4 protocol: ibmmq-secure
5 description: Production Instance 1
6 bindings:
7 ibmmq:
8 groupId: PRODCLSTR1
9 cipherSpec: ANY_TLS12_OR_HIGHER
10 bindingVersion: 0.1.0
11 production2:
12 url: ibmmq://qmgr2host:1414/qm2/DEV.APP.SVRCONN
13 protocol: ibmmq-secure
14 description: Production Instance 2
15 bindings:
16 ibmmq:
17 groupId: PRODCLSTR1
18 bindingVersion: 0.1.0Example using combined strategy
1servers:
2 production:
3 url: 'http://my-ccdt-json-file'
4 protocol: ibmmq-secure
5 description: Production MQ Instance
6 bindings:
7 ibmmq:
8 ccdtQueueManagerName: qm1
9 test:
10 url: ibmmq://qmgrtest:1414/qm2/DEV.APP.SVRCONN
11 protocol: ibmmq-secure
12 description: Test MQ Instance
13 bindings:
14 ibmmq:
15 cipherSpec: ANY_TLS12_OR_HIGHER
16 bindingVersion: 0.1.0Channel Binding Object
This object contains information about the channel representation in IBM MQ. Each channel corresponds to a Queue or Topic within IBM MQ.
Fixed Fields
| Field Name | Type | Description | Applicability [default] | Constraints |
|---|---|---|---|---|
destinationType | string | Defines the type of AsyncAPI channel. | OPTIONAL [topic] | MUST be either topic or queue. For type topic, the AsyncAPI channel name MUST be assumed for the IBM MQ topic string unless overridden. |
queue | Map[string, any] | Defines the properties of a queue. | REQUIRED if destinationType = queue | queue and topic fields MUST NOT coexist within a channel binding |
queue.objectName | string | Defines the name of the IBM MQ queue associated with the channel. | REQUIRED | A value MUST be specified. MUST NOT exceed 48 characters in length. MUST be a valid IBM MQ queue name |
queue.isPartitioned | boolean | Defines if the queue is a cluster queue and therefore partitioned. If true, a binding option MAY be specified when accessing the queue. More information on binding options can be found on this page in the IBM MQ Knowledge Center. | OPTIONAL [false] | If false, binding options SHOULD NOT be specified when accessing the queue. |
queue.exclusive | boolean | Specifies if it is recommended to open the queue exclusively. | OPTIONAL [false] | - |
topic | Map[string, any] | Defines the properties of a topic. | OPTIONAL if destinationType = topic | queue and topic fields MUST NOT coexist within a channel binding. |
topic.string | string | The value of the IBM MQ topic string to be used. | OPTIONAL Note: if specified, SHALL override AsyncAPI channel name. | MUST NOT exceed 10240 characters in length. MAY coexist with topic.objectName |
topic.objectName | string | The name of the IBM MQ topic object. | OPTIONAL Note: if specified, SHALL override AsyncAPI channel name. | MUST NOT exceed 48 characters in length. MAY coexist with topic.string |
topic.durablePermitted | boolean | Defines if the subscription may be durable. | OPTIONAL [true] | - |
topic.lastMsgRetained | boolean | Defines if the last message published will be made available to new subscriptions. | OPTIONAL [false] | - |
maxMsgLength | integer | The maximum length of the physical message (in bytes) accepted by the Topic or Queue. Messages produced that are greater in size than this value may fail to be delivered. More information on the maximum message length can be found on this page in the IBM MQ Knowledge Center. | OPTIONAL [negotiated on IBM MQ channel] | MUST be 0-104,857,600 bytes (100 MB). |
bindingVersion | string | The version of this binding. | OPTIONAL [latest] | - |
This object MUST contain only the properties defined above.
Example for an IBM MQ Topic where topic string is defined by AsyncAPI channel
1channels:
2 user/signedup:Example for AsyncAPI channel mapping to an IBM MQ topic with a specified MQ Topic object
1channels:
2 user/signedup:
3 bindings:
4 ibmmq:
5 destinationType: topic
6 topic:
7 objectName: myTopicName
8 bindingVersion: 0.1.0Example for AsyncAPI channel mapping to an IBM MQ Queue
1channels:
2 user/signedup:
3 bindings:
4 ibmmq:
5 destinationType: queue
6 queue:
7 objectName: myQueueName
8 exclusive: true
9 bindingVersion: 0.1.0Operation Binding Object
This object MUST NOT contain any properties. Its name is reserved for future use.
Message Binding Object
This object contains information about the message representation in IBM MQ.
Fixed Fields
| Field Name | Type | Description | Applicability [default] | Constraints |
|---|---|---|---|---|
type | string | The type of the message. | OPTIONAL [string] | MUST be either string, jms or binary |
headers | string | Defines the IBM MQ message headers to include with this message. More than one header can be specified as a comma separated list. Supporting information on IBM MQ message formats can be found on this page in the IBM MQ Knowledge Center. | OPTIONAL if type = binary | headers MUST NOT be specified if type = string or jms |
description | string1 | Provides additional information for application developers: describes the message type or format. | OPTIONAL | - |
expiry | integer | The recommended setting the client should use for the TTL (Time-To-Live) of the message. This is a period of time expressed in milliseconds and set by the application that puts the message. expiry values are API dependant e.g., MQI and JMS use different units of time and default values for unlimited. General information on IBM MQ message expiry can be found on this page in the IBM MQ Knowledge Center. | OPTIONAL [unlimited] | expiry value MUST be either zero (unlimited) or greater than zero. |
bindingVersion | string | The version of this binding. | OPTIONAL [latest] | - |
This object MUST contain only the properties defined above.
Rich Text Formatting
1 The description field of the IBM MQ message binding object MAY include CommonMark markdown formatting. A minimum markdown syntax as described by CommonMark 0.27 is assumed.
Example for plain text message
1channels:
2 user/signup:
3 publish:
4 message:
5 bindings:
6 ibmmq:
7 type: string
8 bindingVersion: 0.1.0Example for IBM MQ message using JMS
1channels:
2 user/signup:
3 publish:
4 message:
5 bindings:
6 ibmmq:
7 type: jms
8 description: JMS stream message
9 bindingVersion: 0.1.0AsyncAPI example with IBM MQ binding
Example for AsyncAPI user signup
1asyncapi: 2.0.0
2info:
3 title: Account Service
4 version: 1.0.0
5 description: This service is in charge of processing user signups
6servers:
7 production1:
8 url: ibmmq://qmgr1host:1414/qm1/DEV.APP.SVRCONN
9 protocol: ibmmq-secure
10 description: Production Instance 1
11 bindings:
12 ibmmq:
13 groupId: PRODCLSTR1
14 cipherSpec: ANY_TLS12_OR_HIGHER
15 bindingVersion: 0.1.0
16 production2:
17 url: ibmmq://qmgr2host:1414/qm2/DEV.APP.SVRCONN
18 protocol: ibmmq-secure
19 description: Production Instance 2
20 bindings:
21 ibmmq:
22 groupId: PRODCLSTR1
23 cipherSpec: ANY_TLS12_OR_HIGHER
24 bindingVersion: 0.1.0
25channels:
26 user/signedup:
27 bindings:
28 ibmmq:
29 topic:
30 durablePermitted: true
31 bindingVersion: 0.1.0
32 subscribe:
33 message:
34 $ref: '#/components/messages/UserSignedUp'
35 bindings:
36 ibmmq:
37 type: jms
38 description: JMS bytes message
39 bindingVersion: 0.1.0
40components:
41 messages:
42 UserSignedUp:
43 payload:
44 type: object
45 properties:
46 displayName:
47 type: string
48 description: Name of the user
49 email:
50 type: string
51 format: email
52 description: Email of the user