Anypoint MQ REST APIs

The Anypoint MQ APIs enable you to use REST to send and receive messages, administer queues and message exchanges, and analyze results.

Anypoint MQ provides these APIs:

Anypoint MQ Admin API
Anypoint MQ Broker API
Anypoint MQ Stats API

Anypoint MQ portals are available in the Developer portal.

Workflow for an API

The following example with the Broker API illustrates the workflow for accessing an API:

Steps:

An app sends a request to Anypoint MQ and sets how long to hold the lock on the message.
Anypoint MQ sends the message and the lock ID.
The app acknowledges the message and requests Anypoint MQ to delete the message, or the app negatively acknowledges the message and requests Anypoint MQ to make the message available to other apps. The app sends the message ID and lock ID to Anypoint MQ.
If no action is taken and the duration of a lock’s time to live expires, the message is negatively acknowledged and returns to the queue to be available for other apps.

Authorize API Access

Before accessing an API, you need to acquire an access token:

Anypoint MQ Admin API

Get an access token for an Anypoint Platform user.
Anypoint MQ Broker API

Get a token from Anypoint MQ by supplying the client ID and client secret for an MQ app.
Anypoint MQ Stats API

Get an access token for an Anypoint Platform user.

The curl command for each is explained in the API sections.

Anypoint MQ Admin API

The Anypoint MQ Admin API provides access to Anypoint MQ administrative functionality.

You can use the Admin API to create and manage apps, queues, and message exchanges.

If you call the Anypoint MQ Admin API for distinct environments within one minute, the API throttles your requests to 50 transactions per minute (TPM).

You can get the organization ID and environment ID in the payload.txt file that Anypoint Platform creates for any auditable action in MQ. See MQ Audit Logging.

You can get the access token from the Anypoint Platform user. The access token is also known as the Bearer. The access token has a default time to live (TTL) of 60 minutes.

You can use this curl command to get the access token:

curl -X POST -H "Content-Type: application/json" -d '{"username":"USERNAME", "password":"PASSWORD"}' https://anypoint.mulesoft.com/accounts/login

The command returns output similar to:

{
  "access_token": "42424242-4242-4242-4242-424242424242",
  "token_type": "bearer",
  "redirectUrl": "/home/"
}

Create a FIFO Queue in the Admin API Portal

You can create a FIFO queue from the Admin API portal by including the "fifo": true field.

Note: The organization from which you use the Administration portal must have an Anypoint MQ FIFO entitlement. See Anypoint MQ FAQ for the regions where Anypoint MQ is available.

For the following path using the PUT operation:

/organizations/ORGANIZATION_ID/environments/ENVIRONMENT_ID/regions/REGION_ID/destinations/queues/QUEUE_ID

Use this body:

{
  "defaultTtl" : 120000,
  "defaultLockTtl" : 10000,
  "encrypted" : false,
  "fifo" : true
}

Anypoint MQ Broker API

The Anypoint MQ Broker API enables clients to publish, retrieve, and acknowledge messages from queues and message exchanges.

You can get the organization ID and environment ID in the payload.txt file that Anypoint Platform creates for any auditable action in MQ. See MQ Audit Logging.

Getting the access (bearer) token requires using either a command like curl or an app like Postman. The example that follows uses curl. If you are a Windows user, you need to download a curl command before accessing the information.

The access token in this section can only be used with the Broker API. Do not use this access token with the Stats and Admin APIs.

To get the Broker API access token:

Log in to Anypoint Platform.
Click MQ > Client Apps, and then click the blue plus-circle icon to create an app.

Get the client ID and client secret and use these values in the curl command below replacing CLIENT_ID and CLIENT_SECRET:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=client_credentials" "https://mq-us-east-1.anypoint.mulesoft.com/api/v1/authorize"

See the Anypoint MQ FAQ for the regions where Anypoint MQ and FIFO are available.

Submit the curl command.

The command returns output similar to:

{"access_token":"<token>","simple_client":{"envId":"ENVIRONMENT_ID","orgId":"ORGANIZATION_ID"},"token_type":"bearer"}

Use the Anypoint MQ Broker API

These examples use the Anypoint MQ Broker API to publish and consume messages and to test Anypoint MQ from the command line using curl.

You must substitute the placeholder string, 42544254-4254-4254-4254-425442544254 with the proper values for authorization and token strings. These examples use Postman to access the queue.

See the MQ FAQ for the regions where Anypoint MQ and FIFO are available.

Example: Publish a Message

The following curl command publishes a message:

curl -X PUT -H "Content-Type: application/json" \
-H "Authorization: bearer 42544254-4254-4254-4254-425442544254" \
-H "Cache-Control: no-cache" \
-H "Postman-Token: 42544254-4254-4254-42544254-425442544254" \
-d '{ \
  "properties": {
    "userDefinedHeader": "User defined stuff",
    "anotherUserDefinedHeader": "Random stuff"
  },

  "body": "This is a message payload"
}
' "https://mq-us-east-1.anypoint.mulesoft.com/api/v1/organizations/42544254-4254-4254-4254-425442544254/environments/42544254-4254-4254-4254-425442544254/destinations/postmanExchange/messages/552"

Example: Retrieve a Message

The following curl command gets a message:

curl -X GET -H "Authorization: bearer 42544254-4254-4254-4254-425442544254" \
-H "Cache-Control: no-cache" \
-H "Postman-Token: 42544254-4254-4254-4254-425442544254" \
"https://mq-us-east-1.anypoint.mulesoft.com/api/v1/organizations/42544254-4254-4254-4254-425442544254/environments/42544254-4254-4254-4254-425442544254/destinations/postmanQueue/messages?pollingTime=10000&batchSize=1&lockTtl=10000"

You can control whether to show the message payload in the response using the payloadVisibility query parameter. This parameter is useful when retrieving large payloads.

The payloadVisibility parameter takes the following options:

full: Shows the message payload in the response.
This option is the default.
none: Hides the message payload in the response.
conditional: Hides the message payload if the payload size is larger than 1 MB.

If the payload is hidden because payloadVisibility is set to none or conditional, the response includes payloadHidden=true in the message header.

The following curl command gets a message and payload, displaying the payload only if the payload size is smaller than 1 MB:

curl -X GET -H "Authorization: bearer 42544254-4254-4254-4254-425442544254" \
-H "Cache-Control: no-cache" \
-H "Postman-Token: 42544254-4254-4254-4254-425442544254" \
"https://mq-us-east-1.anypoint.mulesoft.com/api/v1/organizations/42544254-4254-4254-4254-425442544254/environments/42544254-4254-4254-4254-425442544254/destinations/postmanQueue/messages?pollingTime=10000&batchSize=1&lockTtl=10000&payloadVisibility=conditional"

Anypoint MQ Stats API

The Anypoint MQ Stats API enables you to get statistics and metrics for queues and message exchanges.

You can use the Anypoint MQ Stats API to perform statistical analysis of queue performance.

Use the Stats API to retrieve:

Anypoint MQ metrics:
- Near real-time statistics for queues
- Historical statistics for queues
- Historical statistics for message exchanges
Usage metrics

View your entire organization’s usage of Anypoint MQ for billing purposes: Usage per environment Usage per organization
Statistics for queues and message exchanges
Number of messages currently in a queue

For more information, see the Anypoint MQ Stats API in the MuleSoft developer portal.

Use the Anypoint MQ Stats API

To access the Anypoint MQ Stats API, you must first authenticate using the Anypoint Access Management API.

To use the Stats API, you can get the access token from the Anypoint Platform user. The access token is also known as the Bearer. The default time to live (TTL) for the access token is 60 minutes. You can get the organization ID and environment ID in the payload.txt file that Anypoint Platform creates for any auditable action in MQ. See MQ Audit Logging.

You can use this curl command to get the access token:

curl -X POST -H "Content-Type: application/json" -d '{"username":"USERNAME", "password":"PASSWORD"}' https://anypoint.mulesoft.com/accounts/login

This returns output similar to:

{
  "access_token": "42424242-4242-4242-4242-424242424242",
  "token_type": "bearer",
  "redirectUrl": "/home/"
}

Current Statistics for Queues

You can get a snapshot of the number of messages in the queue and how many are in-flight. See Anypoint MQ Terminology for a definition of in-flight messages. The data updates in almost real-time.

Stats API responses and message status changes include up to 60 seconds of inconsistency due to internal post-processing activities. Message status changes include from in-queue to in-flight, from in-flight to in-queue, and from in-flight to deleted. For this reason, don’t use the Stats API for syncing processing actions, such as checking if the queue is empty.

The Stats API can fetch statistics for multiple queues and returns a comma-separated list.

/queues?destinationIds={queue1},{queue2}