Chapter 5. HornetQ REST Interface Basics

5.1. Queue and Topic Resources
5.2. Queue Resource Response Headers
5.3. Topic Resource Respones Headers

The HornetQ REST interface publishes a variety of REST resources to perform various tasks on a queue or topic. Only the top-level queue and topic URI schemes are published to the outside world. You must discover all over resources to interact with by looking for and traversing links. You'll find published links within custom response headers and embedded in published XML representations. Let's look at how this works.

5.1. Queue and Topic Resources

To interact with a queue or topic you do a HEAD or GET request on the following relative URI pattern:

/queues/{name}
/topics/{name}

The base of the URI is the base URL of the WAR you deployed the HornetQ REST server within as defined in the Installation and Configuration section of this document. Replace the {name} string within the above URI pattern with the name of the queue or topic you are interested in interacting with. For example if you have configured a JMS topic named "foo" within your hornetq-jms.xml file, the URI name should be "jms.topic.foo". If you have configured a JMS queue name "bar" within your hornetq-jms.xml file, the URI name should be "jms.queue.bar". Internally, HornetQ prepends the "jms.topic" or "jms.queue" strings to the name of the deployed destination. Next, perform your HEAD or GET request on this URI. Here's what a request/response would look like.

HEAD /queues/jms.queue.bar HTTP/1.1
Host: example.com

--- Response ---
HTTP/1.1 200 Ok
msg-create: http://example.com/queues/jms.queue.bar/create
msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers

The HEAD or GET response contains a number of custom response headers that are URLs to additional REST resources that allow you to interact with the queue or topic in different ways. It is important not to rely on the scheme of the URLs returned within these headers as they are an implementation detail. Treat them as opaque and query for them each and every time you initially interact (at boot time) with the server. If you treat all URLs as opaque then you will be isolated from implementation changes as the HornetQ REST interface evolves over time.

5.2. Queue Resource Response Headers

Below is a list of response headers you should expect when interacting with a Queue resource.

msg-create: This is a URL you POST messages to. The semantics of this link are described in Chapter 4.
msg-create-with-id: This is a URL template you POST message to. The semantics of this link are described in Chapter 4.
msg-pull-consumers: This is a URL for creating consumers that will pull from a queue. The semantics of this link are described in Chapter 5.
msg-push-consumers: This is a URL for registering other URLs you want the HornetQ REST server to push messages to. The semantics of this link are described in Chapter 6

5.3. Topic Resource Respones Headers

Below is a list of response headers you should expect when interacting with a Topic resource.

msg-create: This is a URL you POST messages to. The semantics of this link are described in Chapter 4.
msg-create-with-id: This is a URL template you POST messages to. The semantics of this link are described in Chapter 4.
msg-pull-subscriptions: This is a URL for creating subscribers that will pull from a topic. The semantics of this link are described in Chapter 5.
msg-push-subscriptions: This is a URL for registering other URLs you want the HornetQ REST server to push messages to. The semantics of this link are described in Chapter 6.