Anypoint MQ Bindings
This document defines how to describe Anypoint MQ-specific information in AsyncAPI documents.
Anypoint MQ is MuleSoft's multi-tenant, cloud messaging service and is fully integrated with Anypoint Platform.
Versions
The version of this bindings specification is 0.1.0.
This is also the bindingVersion for all binding objects defined by this specification.
In any given binding object, latest MAY alternatively be used to refer to the currently latest published version of this bindings specification.
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.
Protocol
These bindings use the anypointmq protocol in AsyncAPI documents to denote connections to and interactions with Anypoint MQ message brokers.
The Anypoint MQ protocol is based on invocations of the Anypoint MQ Broker REST API.
Server Object
The fields of the standard Server Object are constrained and interpreted as follows:
Note that the choice of a particular Anypoint MQ client app (via its client ID and secret) decides the Anypoint Platform organization ID and environment (ID) to be those in which this client app is defined. See the Anypoint MQ documentation for details on how to configure Anypoint MQ client apps.
Server Binding Object
This object MUST NOT contain any properties. Its name is reserved for future use.
Channel Binding Object
The Anypoint MQ Channel Binding Object is defined by a JSON Schema, which defines these fields:
Note that an Anypoint MQ exchange can only be sent to, not received from. To receive messages sent to an exchange, an intermediary queue must be defined and bound to the exchange. In this bindings specification, these intermediary queues are not exposed in the AsyncAPI document. Instead, it is simply assumed that whenever messages must be received from an exchange, such an intermediary queue is involved yet invisible in the AsyncAPI document.
Examples
The following example shows two channels where does not apply any bindings and the second one applying anyointmq bindings.
1channels:2 userSignup:3 address: 'user/signup'4 description: |5 This application receives command messages from this channel about users to sign up.6 Minimal configuration, omitting a channel binding object.7 messages:8 #...910 userSignup:11 address: 'user/signup'12 description: |13 This application sends events to this channel about users that have signed up.14 Explicitly provides a channel binding object.15 messages:16 #...17 bindings:18 anypointmq:19 destination: user-signup-exchg20 destinationType: exchange21 bindingVersion: '0.1.0'
Operation Binding Object
This object MUST NOT contain any properties. Its name is reserved for future use.
Message Binding Object
The Anypoint MQ Message Binding Object defines these fields:
| Field Name | Type | Description |
|---|---|---|
headers | Schema Object | Reference Object | OPTIONAL. A Schema object containing the definitions for Anypoint MQ-specific headers (so-called protocol headers). This schema MUST be of type object and have a properties key. Examples of Anypoint MQ protocol headers are messageId and messageGroupId. |
bindingVersion | string | OPTIONAL, defaults to latest. The version of this binding. |
Note that application headers must be specified in the headers field of the standard Message Object and are transmitted in the properties section of the Anypoint MQ message.
In contrast, protocol headers such as messageId must be specified in the headers field of the message binding object and are transmitted in the headers section of the Anypoint MQ message.
Examples
The following example shows a channels object with two channels, each having one operation (subscribe or publish) with one message. Only the message of the subscribe operation has a message binding object for anypointmq:
1channels:2 userSignup:3 address: 'user/signup'4 messages:5 #...6 userSignup:7 address: 'user/signup'8 messages:9 userSignupMessage:10 headers:11 type: object12 properties:13 correlationId:14 description: Correlation ID set by application15 type: string16 payload:17 type: object18 properties:19 #...20 correlationId:21 description: Correlation ID is specified as a header and transmitted in the Anypoint MQ message properties section22 location: $message.header#/correlationId23 bindings:24 anypointmq:25 headers:26 type: object27 properties:28 messageId:29 type: string30 bindingVersion: '0.1.0'
Complete Example
The following is a complete, simple AsyncAPI document illustrating the usage of all binding objects defined in this bindings specification, with all their fields.
1asyncapi: 3.0.02info:3 title: Example with Anypoint MQ4 version: 0.0.15servers:6 development:7 host: mq-us-east-1.anypoint.mulesoft.com8 pathname: /api9 protocol: anypointmq10 protocolVersion: v111 description: >12 Anypoint MQ broker for development, in the US East (N. Virginia) runtime13 plane1415 under management of the US control plane.16 security:17 - $ref: '#/components/securitySchemes/oauthDev'18 production:19 host: mq-eu-central-1.eu1.anypoint.mulesoft.com20 pathname: /api21 protocol: anypointmq22 protocolVersion: v123 description: >24 Anypoint MQ broker for production, in the EU Central (Frankfurt) runtime25 plane2627 under management of the EU control plane.28 security:29 - $ref: '#/components/securitySchemes/oauthProd'30 bindings:31 anypointmq:32 bindingVersion: 0.1.033channels:34 user/signup:35 address: user/signup36 messages:37 signUpUser.message:38 contentType: application/json39 headers:40 type: object41 properties:42 correlationId:43 description: Correlation ID set by application44 type: string45 payload:46 type: object47 properties:48 username:49 type: string50 minLength: 351 correlationId:52 description: >-53 Correlation ID is specified as a header and transmitted in the54 Anypoint MQ message properties section55 location: $message.header#/correlationId56 bindings:57 anypointmq:58 headers:59 type: object60 properties:61 messageId:62 type: string63 bindingVersion: 0.1.064 description: >65 This application receives command messages from this channel about users66 to sign up.67 bindings:68 anypointmq:69 destination: user-signup-queue70 destinationType: fifo-queue71 bindingVersion: 0.1.072operations:73 signUpUser:74 action: receive75 channel:76 $ref: '#/channels/user~1signup'77 description: >78 This application receives command messages via this operation about users79 to sign up.80 messages:81 - $ref: '#/channels/user~1signup/messages/signUpUser.message'82components:83 securitySchemes:84 oauthDev:85 type: oauth286 flows:87 clientCredentials:88 tokenUrl: 'https://mq-us-east-1.anypoint.mulesoft.com/api/v1/authorize'89 scopes: {}90 oauthProd:91 type: oauth292 flows:93 clientCredentials:94 tokenUrl: 'https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api/v1/authorize'95 scopes: {}