anypointmq

Found an error? Have a suggestion?Edit this page on GitHub

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:

Server Object Field NameValues for Anypoint MQ ProtocolDescription
protocolanypointmqREQUIRED. MUST be anypointmq for the scope of this specification.
hoste.g., https://mq-us-east-1.anypoint.mulesoft.comREQUIRED. MUST be the endpoint HOST part of the URL of the Anypoint MQ Broker REST API. Valid examples are https://mq-us-east-1.anypoint.mulesoft.com and https://mq-eu-central-1.eu1.anypoint.mulesoft.com (and not https://mq-us-east-1.anypoint.mulesoft.com/api, or https://.../api/v1).
pathnamee.g., /apiREQUIRED. MUST be the endpoint path part of the URL of the Anypoint MQ Broker REST API excluding the final major version indicator (e.g., v1). Valid examples are /api and (and not https://.../api/v1).
protocolVersione.g., v1OPTIONAL, defaults to v1. If present MUST be the major version indicator of the Anypoint MQ Broker REST API omitted from the url, e.g. v1.
securitysuitably configured OAuth 2.0 client credentials grant typeREQUIRED. Authentication against the MuleSoft-hosted Anypoint MQ message brokers uses the OAuth 2.0 client credentials grant type. At runtime, the client ID and client secret values of an Anypoint MQ client app must be supplied. Also, the OAuth 2.0 scopes are currently not client-configurable. The security field of the server object MUST correctly match these constraints.

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:

Field NameTypeDescription
destinationstringOPTIONAL, defaults to the channel name. The destination (queue or exchange) name for this channel. SHOULD only be specified if the channel name differs from the actual destination name, such as when the channel name is not a valid destination name in Anypoint MQ.
destinationTypestringOPTIONAL, defaults to queue. The type of destination, which MUST be either exchange or queue or fifo-queue. SHOULD be specified to document the messaging model (publish/subscribe, point-to-point, strict message ordering) supported by this channel.
bindingVersionstringOPTIONAL, defaults to latest. The version of this binding.

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      #...
9
10  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-exchg
20        destinationType: exchange
21        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 NameTypeDescription
headersSchema Object | Reference ObjectOPTIONAL. 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.
bindingVersionstringOPTIONAL, 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: object
12          properties:
13            correlationId:
14              description: Correlation ID set by application
15              type: string
16        payload:
17          type: object
18          properties:
19            #...
20        correlationId:
21          description: Correlation ID is specified as a header and transmitted in the Anypoint MQ message properties section
22          location:    $message.header#/correlationId
23        bindings:
24          anypointmq:
25            headers:
26              type: object
27              properties:
28                messageId:
29                  type: string
30            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.0
2info:
3  title: Example with Anypoint MQ
4  version: 0.0.1
5servers:
6  development:
7    host: mq-us-east-1.anypoint.mulesoft.com
8    pathname: /api
9    protocol: anypointmq
10    protocolVersion: v1
11    description: >
12      Anypoint MQ broker for development, in the US East (N. Virginia) runtime
13      plane 
14
15      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.com
20    pathname: /api
21    protocol: anypointmq
22    protocolVersion: v1
23    description: >
24      Anypoint MQ broker for production, in the EU Central (Frankfurt) runtime
25      plane 
26
27      under management of the EU control plane.
28    security:
29      - $ref: '#/components/securitySchemes/oauthProd'
30    bindings:
31      anypointmq:
32        bindingVersion: 0.1.0
33channels:
34  user/signup:
35    address: user/signup
36    messages:
37      signUpUser.message:
38        contentType: application/json
39        headers:
40          type: object
41          properties:
42            correlationId:
43              description: Correlation ID set by application
44              type: string
45        payload:
46          type: object
47          properties:
48            username:
49              type: string
50              minLength: 3
51        correlationId:
52          description: >-
53            Correlation ID is specified as a header and transmitted in the
54            Anypoint MQ message properties section
55          location: $message.header#/correlationId
56        bindings:
57          anypointmq:
58            headers:
59              type: object
60              properties:
61                messageId:
62                  type: string
63            bindingVersion: 0.1.0
64    description: >
65      This application receives command messages from this channel about users
66      to sign up.
67    bindings:
68      anypointmq:
69        destination: user-signup-queue
70        destinationType: fifo-queue
71        bindingVersion: 0.1.0
72operations:
73  signUpUser:
74    action: receive
75    channel:
76      $ref: '#/channels/user~1signup'
77    description: >
78      This application receives command messages via this operation about users
79      to sign up.
80    messages:
81      - $ref: '#/channels/user~1signup/messages/signUpUser.message'
82components:
83  securitySchemes:
84    oauthDev:
85      type: oauth2
86      flows:
87        clientCredentials:
88          tokenUrl: 'https://mq-us-east-1.anypoint.mulesoft.com/api/v1/authorize'
89          scopes: {}
90    oauthProd:
91      type: oauth2
92      flows:
93        clientCredentials:
94          tokenUrl: 'https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api/v1/authorize'
95          scopes: {}
Was this helpful?
Help us improve the docs by adding your contribution.
OR
Github:AsyncAPICreate Issue on GitHub