ActiveMQ implements a RESTful API to messaging which allows any web capable device to publish or consume messages using a regular HTTP POST or GET.

If you are interested in messaging directly from web browsers you might wanna check out our Ajax or WebSockets support or try running the REST examples

Mapping of REST to JMS

To publish a message use a HTTP POST. To consume a message use HTTP DELETE or GET.

ActiveMQ has a Servlet that takes care of the integration between HTTP and the ActiveMQ dispatcher.

You can map a URI to the servlet and then use the relative part of the URI as the topic or queue name. e.g. you could HTTP POST to

which would publish the contents of the HTTP POST to the orders.input queue on JMS.

Similarly you could perform a HTTP DELETE GET on the above URL to read from the same queue. In this case we will map the MessageServlet from ActiveMQ to the URI

and configure it to accept the URI as a queue destination. We can do similar things to support topic destinations too.

We can use the HTTP session to denote a unique publisher or consumer.

Note that strict REST requires that GET be a read only operation; so strictly speaking we should not use GET to allow folks to consume messages. Though we allow this as it simplifies HTTP/DHTML/Ajax integration somewhat.

For a more cleaner mapping of a simple transfer protocol to different languages, you might wanna take a look at Stomp.

Default configuration

Until version 5.8, REST API was part of the Web Samples and was mapped to http://localhost:8161/demo/message url. From 5.8 onwards, the API is available by default at http://localhost:8161/api/message url. Also, starting with 5.8, web server is secured by default (see Web Console for more information), so have that in mind when trying to use it. Examples below will assume new api location and secured web server.

Producing

You cam produce by sending a POST request to the server, like

Timeouts

When reading from a queue we might not have any messages. We can use a timeout query parameter to indicate how long we are prepared to wait for a message to arrive. This allows us to poll or block until a message arrives.

Couple this with HTTP 1.1 keep-alive sockets and pipeline processing we can have efficient access to JMS over HTTP.

Obviously if your client is Java then using ActiveMQ's JMS API is the fastest and most efficient way to work with the message broker; however, if you are not using Java or prefer the simplicity of HTTP then it should be fairly efficient, especially if your HTTP client supports keep-alive sockets and pipeline processing.

Consuming

When consuming messages using the REST API, you have to keep session alive between GET requests, or you'll create a separate consumer for every request and due to prefetch limit your succeeding call will hang.

For example, you can use wget to consume messages, like this:

Also, if you plan to have multiple consumer using REST, it's advisable to set prefetch size to 1 so all consumers have an equal chance of getting the message. You can do that by passing a special parameter to the MessageServlet

in the webapps/demo/WEB-INF/web.xml

Consuming without sessions

Since 5.2.0 you can use clientId parameter to avoid storing actual JMS consumer in the request session. When using this approach, you don't need to keep sessions alive between requests, you just need to use the same clientId every time.

Every such call will use the same JMS consumer and deliver messages send to it by the broker.

In 5.4.1 it's also possible to unsubscribe the client. It's done by sending a POST call with clientId and action=unsubscribe parameters to the server, like

Consuming with selectors

As of ActiveMQ 5.4.0, you can use selectors when consuming using REST protocol. To do that, just specify the appropriate header with selector. To define a selector for the consumer, you have to provide it in an appropriate HTTP header. By default selector header name is selector, so the following example

should consume only messages that have test property set to 2.

You can change the name of the selector header using the org.apache.activemq.selectorName Servlet context property in WEB-INF/web.xml, such as

For more info, take a look at RestTest

Content Types

By default messages are sent to the consumers with text/xml content type. Your REST-based application may expect JSON response instead of XML one. In that case, you can configure the servlet to send responses back by adding something like this

to your WEB-INF/web.xml.

A default content type can also be overridden using request headers. Specifying xml=true or json=true URL parameter you'll get a response with the desired content type.

Security

Since 5.7.0 release REST API can connect to the secured brokers. The API uses basic authentication header format to get username and password information.

For example, with curl you can do something like

Also, you might want to enable ssl for your connections. To do that, just uncomment SecureConnector in conf/jetty.xml

Rest Management

Starting with version 5.8 we provide a REST management API for the broker. Using Jolokia JMX-HTTP bridge it's possible to access all broker metrics (like memory usage) and execute management operations (like purging queues) using REST API. By default the management API is exposed at http://localhost:8161/api/jolokia/ URL. So you can for example get basic broker data with

or to be more specific, total consumer count with

For more information on Jolokia protocol, see its reference manual. An API like this makes it easy to script monitoring and management operations against the broker, see also How can I monitor ActiveMQ?

© 2004-2011 The Apache Software Foundation.
Apache ActiveMQ, ActiveMQ, Apache, the Apache feather logo, and the Apache ActiveMQ project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
Graphic Design By Hiram