Menu
Amazon MQ
REST API Reference

Brokers

This is a collection of brokers. A broker is a message broker environment running on Amazon MQ. It is the basic building block of Amazon MQ. For more information, see Broker in the Amazon MQ Developer Guide.

URI

/v1/brokers

HTTP Methods

GET

Returns a list of all brokers.

Query

Name Type Description

maxResults

integer

The maximum number of brokers that Amazon MQ can return per page (20 by default). This value must be an integer from 5 to 100.

nextToken

string

The token that specifies the next page of results Amazon MQ should return. To request the first page, leave nextToken empty.

Response

Status Code Schema Description

200

ListBrokersOutput

HTTP Status Code 200: OK.

POST

Creates a broker.

Note

This API is asynchronous.

Body

Name Type Description

CreateBrokerInput

CreateBrokerInput

Creates a broker using the specified properties.

Response

Status Code Schema Description

200

CreateBrokerOutput

HTTP Status Code 200: OK.

Errors

Errors

Status Code Schema Description

400

Error

HTTP Status Code 400: Bad request due to incorrect input. Correct your request and then retry it.

401

Error

HTTP Status Code 401: Unauthorized request. The provided credentials couldn't be validated.

404

Error

HTTP Status Code 403: Access forbidden. Correct your credentials and then retry your request.

409

Error

HTTP Status Code 409: Conflict. This Broker name already exists. Retry your request with another name.

500

Error

HTTP Status Code 500: Unexpected internal server error. Retrying your request might resolve the issue.

Schemas

Request Schemas

Example CreateBrokerInput

{ "brokerName": "MyBroker", "hostInstanceType": "mq.m4.large", "engineType": "ActiveMQ", "engineVersion": "5.15.0", "configuration": { "id": "c-1234a5b6-78cd-901e-2fgh-3i45j6k178l9", "revision": 3 }, "creatorRequestId": "kji10h98-76g5-43f2-10ed-9cb8a7654321", "deploymentMode": "ACTIVE_STANDBY_MULTI_AZ", "publiclyAccessible": true, "subnetIds": [ "subnet-12a3b45c", "subnet-67d8e90f" ], "securityGroups": [ "sg-a1b234cd", "sg-e5f678gh" ], "autoMinorVersionUpgrade": true, "maintenanceWindowStartTime": { "timeOfDay": "13:00", "dayOfWeek": "SUNDAY", "timeZone": "UTC" }, "users": [{ "password": "MyPassword456", "groups": [ "admins" ], "consoleAccess": true, "username": "jane.doe" }, { "password": "MyPassword654", "groups": [ "support" ], "consoleAccess": true, "username": "paolo.santos" }] }

Response Schemas

Example CreateBrokerOutput

{ "brokerId" : "b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9", "brokerArn": "arn:aws:mq:us-east-1:123456789012:broker:MyBroker:b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9" }

Example ListBrokersOutput

{ "nextToken": "eyEXAMPLEW9uIjoidjEiLCJzZXJpYWxpemVkUGFnaW5hdGlvblRva2VuIjoiZXlKMGIydGxia1JoZEdFaU9uc2liR0Z6ZEMxelpXVnVMV0p5YjJ0bGNpMWhjbTRpT2lJeEluMTkifQ==", "brokerSummaries": [ { "brokerId" : "b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9", "brokerArn": "arn:aws:mq:us-east-1:123456789012:broker:MyBroker1:b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9", "brokerState": "RUNNING", "brokerName": "MyBroker1", "deploymentMode": "SINGLE_INSTANCE", "hostInstanceType": "mq.t2.micro", "created": "2017-11-28T01:23:45.678Z" }, { "brokerId" : "b-9876l5k4-32ji-109h-8gfe-7d65c4b132a1", "brokerArn": "arn:aws:mq:us-east-1:123456789012:broker:MyBroker2:b-9876l5k4-32ji-109h-8gfe-7d65c4b132a1", "brokerState": "DELETION_IN_PROGRESS", "brokerName": "MyBroker2", "deploymentMode": "ACTIVE_STANDBY_MULTI_AZ", "hostInstanceType": "mq.m4.large", "created": "2017-11-29T01:23:45.678Z" } ] }

Example Error

{ "errorAttribute": "TheAttributeWhichCausedTheError", "message": "This is the description of the error and the steps to resolve the issue." }

Attributes

CreateBrokerInput

Attribute Type Description

autoMinorVersionUpgrade

Boolean

Required

Enables automatic upgrades to new minor versions for brokers, as Apache releases the versions. The automatic upgrades occur during the maintenance window of the broker or after a manual broker reboot.

brokerName

string

Required

The name of the broker. This value must be unique in your AWS account, 1-50 characters long, must contain only letters, numbers, dashes, and underscores, and must not contain whitespaces, brackets, wildcard characters, or special characters.

configuration

ConfigurationId

A list of information about the configuration.

creatorRequestId

string

The unique ID that the requester receives for the created broker. Amazon MQ passes your ID with the API action.

Note

We recommend using a Universally Unique Identifier (UUID) for the creatorRequestId. You may omit the creatorRequestId if your application doesn't require idempotency.

deploymentMode

enum

Required

The deployment mode of the broker.

Possible values: SINGLE_INSTANCE, ACTIVE_STANDBY_MULTI_AZ

SINGLE_INSTANCE creates a single-instance broker in a single Availability Zone. ACTIVE_STANDBY_MULTI_AZ creates an active/standby broker for high availability.

engineType

enum

Required

The type of broker engine.

Note

Currently, Amazon MQ supports only ACTIVEMQ.

engineVersion

enum

Required

The version of the broker engine.

Note

Currently, Amazon MQ supports only 5.15.0.

hostInstanceType

enum

Required

The broker's instance type.

Possible values: mq.t2.micro, mq.m4.large

maintenanceWindowStartTime

WeeklyStartTime

The parameters that determine the WeeklyStartTime.

publiclyAccessible

Boolean

Required

Enables connections from applications outside of the VPC that hosts the broker's subnets.

securityGroups

array

Required

The list of rules (1 minimum, 125 maximum) that authorize connections to brokers.

subnetIds

array

Required

The list of groups (2 maximum) that define which subnets and IP ranges the broker can use from different Availability Zones. A SINGLE_INSTANCE deployment requires one subnet (for example, the default subnet). An ACTIVE_STANDBY_MULTI_AZ deployment requires two subnets.

users

array

Required

The list of ActiveMQ users (persons or applications) who can access queues and topics. This value can contain only alphanumeric characters, dashes, periods, underscores, and tildes (- . _ ~). This value must be 2-100 characters long.

ConfigurationId

Attribute Type Description

id

string

Required

The unique ID that Amazon MQ generates for the configuration.

revision

integer

The revision number of the configuration.

WeeklyStartTime

Attribute Type Description

dayOfWeek

string

Required

The day of the week.

Possible values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY

timeOfDay

string

Required

The time, in 24-hour format.

timeZone

string

The time zone, UTC by default, in either the Country/City format, or the UTC offset format.

User

Attribute Type Description

consoleAccess

Boolean

Enables access to the the ActiveMQ Web Console for the ActiveMQ user.

groups

array

The list of groups (20 maximum) to which the ActiveMQ user belongs. This value can contain only alphanumeric characters, dashes, periods, underscores, and tildes (- . _ ~). This value must be 2-100 characters long.

password

string (password)

Required

The password of the ActiveMQ user. This value must be at least 12 characters long, must contain at least 4 unique characters, and must not contain commas.

username

string

Required

The username of the ActiveMQ user. This value can contain only alphanumeric characters, dashes, periods, underscores, and tildes (- . _ ~). This value must be 2-100 characters long.

CreateBrokerOutput

Attribute Type Description

brokerArn

string

The Amazon Resource Name (ARN) of the broker.

brokerId

string

The unique ID that Amazon MQ generates for the broker.

ListBrokersOutput

Attribute Type Description

brokerSummaries

array

A list of information about all brokers.

nextToken

string

The token that specifies the next page of results Amazon MQ should return. To request the first page, leave nextToken empty.

BrokerSummary

Attribute Type Description

brokerArn

string

The Amazon Resource Name (ARN) of the broker.

brokerId

string

The unique ID that Amazon MQ generates for the broker.

brokerName

string

The name of the broker. This value must be unique in your AWS account, 1-50 characters long, must contain only letters, numbers, dashes, and underscores, and must not contain whitespaces, brackets, wildcard characters, or special characters.

brokerState

enum

The status of the broker.

Possible values: CREATION_IN_PROGRESS, CREATION_FAILED, DELETION_IN_PROGESS, RUNNING, REBOOT_IN_PROGRESS

created

string (date-time)

The time when the broker was created.

deploymentMode

enum

Required

The deployment mode of the broker.

Possible values: SINGLE_INSTANCE, ACTIVE_STANDBY_MULTI_AZ

SINGLE_INSTANCE creates a single-instance broker in a single Availability Zone. ACTIVE_STANDBY_MULTI_AZ creates an active/standby broker for high availability.

hostInstanceType

enum

The broker's instance type.

Possible values: mq.t2.micro, mq.m4.large

Error

Attribute Type Description

errorAttribute

string

The attribute which caused the error.

message

string

The explanation of the error.