RESTful Messaging

The main goal of this specification is to be able to exchange any type of content with a queue or topic endpoint through a simple protocol.  This draft was originally written as a facade for JMS so many parts of it are not RESTful at all.  We envision vast improvements (or even a complete rewrite) to the interface to make it more compact and a cleaner overall RESTful design.  The idea with the first draft is to get ideas flowing.

The RESTFul Interface for Queues

 

send

POST /queues/{queue-name}?persistent=[true|false]&priority=[0-9+]&timeToLive=[0-9+]

 

Response is 204 NO-CONTENT on success.  All query parameters optional

 

 

Receive and consume a message

POST /queues/{queue-name}/head?wait=[0-9+]

 

Wait is optional.  Defaults to wait forever.

 

 

 

Browse

GET /queues/{queue-name}/browser

 

Returns HTML document with links to message you can view.

 

Dedicated Queue Receivers

Dedicated queues receivers are JMS message consumers attached to a specific session.

 

Create a dedicated receiver that you can pull from.

 

PUT /queues/{queue-name}/receivers/{receiver-id}

If you pass an ACCEPT header this will create a JMS selector that filters message for only a specific media type.  So, if you pass an ACCEPT header of 'application/xml' this receiver will only get message of CONTENT-TYPE 'application/xml'

 

 

Delete a dedicated receiver

DELETE /queues/{queue-name}/receivers/{receiver-id} 

 

Get the current message that is in the receiver's buffer.  This does not consume/acknowledge the message

 

GET /queues/{queue-name}/receivers/{receiver-id}/head?wait=[0-9+]

 

Acknowledge the current message that is in the receiver buffer.

 

DELETE /queues/{queue-name}/receivers/{receiver-id}/head

 

FYI, this is idempotent still!

 

get and acknowledge from the receiver at the same time

POST /queues/{queue-name}/receivers/{reciever-id}/head

 

 

 

Queue Message listeners

You can register a URI to post to when a message is sent to the queue.  This registers a MessageListener with the queue.  When the message is received, on the server, it send the message to the registered URI.

 

Create a message listener

 

PUT /queues/{queue-name}/listeners/{listener-id}

You must send a string that is the URI you want to send the message to.  The content-type can be anything, "text/plain" or whatever.

 

If you pass an ACCEPT header this will create a JMS selector that filters message for only a specific media type.  So, if you pass an ACCEPT header of 'application/xml' this receiver will only get message of CONTENT-TYPE 'application/xml'

 

Delete the listener

DELETE /queues/{queue-name}/receivers/{receiver-id} 

The RESTFul Interface for Topics

 

send

POST /topics/{topic-name}?persistent=[true|false]&priority=[0-9+]&timeToLive=[0-9+]

 

Response is 204 NO-CONTENT on success.  All query parameters optional

 

Dedicated Topic Receivers

Dedicated topic receivers are JMS message consumers attached to a specific session.

 

Create a dedicated receiver that you can pull from.

 

PUT /topics/{topic-name}/receivers/{receiver-id}

If you pass an ACCEPT header this will create a JMS selector that filters message for only a specific media type.  So, if you pass an ACCEPT header of 'application/xml' this receiver will only get message of CONTENT-TYPE 'application/xml'

 

 

Delete a dedicated receiver

DELETE /topics/{topic-name}/receivers/{receiver-id} 

 

Get the current message that is in the receiver's buffer.  This does not consume/acknowledge the message

 

GET /topics/{topic-name}/receivers/{receiver-id}/head?wait=[0-9+]

 

Acknowledge the current message that is in the receiver buffer.

 

DELETE /topics/{topic-name}/receivers/{receiver-id}/head

 

FYI, this is idempotent still!

 

get and acknowledge from the receiver at the same time

POST /topics/{topic-name}/receivers/{receiver-id}/head

 

 

 

Topic Message listeners

You can register a URI to post to when a message is sent to this dedicated topic listener.  This registers a MessageListener with the queue.  When the message is received, on the server, it send the message to the registered URI.

 

Create a message listener

 

PUT /topics/{topic-name}/listeners/{listener-id}

You must send a string that is the URI you want to send the message to.  The content-type can be anything, "text/plain" or whatever.

 

If you pass an ACCEPT header this will create a JMS selector that filters message for only a specific media type.  So, if you pass an ACCEPT header of 'application/xml' this receiver will only get message of CONTENT-TYPE 'application/xml'

 

Delete the listener

DELETE /topics/{topic-name}/receivers/{receiver-id} 

 

 

 

 

The RESTFul Interface for Durable Topics

 

send

POST /topics/{topic-name}?persistent=[true|false]&priority=[0-9+]&timeToLive=[0-9+]

 

Response is 204 NO-CONTENT on success.  All query parameters optional

 

 

Dedicated Durable Topic Receivers

Dedicated topic receivers are JMS message consumers attached to a specific session.

 

Create a dedicated receiver that you can pull from.

 

PUT /topics/{topic-name}/durable/receivers/{receiver-id}

If you pass an ACCEPT header this will create a JMS selector that filters message for only a specific media type.  So, if you pass an ACCEPT header of 'application/xml' this receiver will only get message of CONTENT-TYPE 'application/xml'

 

 

Delete a dedicated receiver

DELETE /topics/{topic-name}/durable/receivers/{receiver-id} 

 

Get the current message that is in the receiver's buffer.  This does not consume/acknowledge the message

 

GET /topics/{topic-name}/durable/receivers/{receiver-id}/head?wait=[0-9+]

 

Acknowledge the current message that is in the receiver buffer.

 

DELETE /topics/{topic-name}/durable/receivers/{receiver-id}/head

 

FYI, this is idempotent still!

 

get and acknowledge from the receiver at the same time

POST /topics/{topic-name}/durable/receivers/{receiver-id}/head

 

 

 

Topic Message listeners

You can register a URI to post to when a message is sent to this dedicated topic listener.  This registers a MessageListener with the queue.  When the message is received, on the server, it send the message to the registered URI.

 

Create a message listener

 

PUT /topics/{topic-name}/durable/listeners/{listener-id}

You must send a string that is the URI you want to send the message to.  The content-type can be anything, "text/plain" or whatever.

 

If you pass an ACCEPT header this will create a JMS selector that filters message for only a specific media type.  So, if you pass an ACCEPT header of 'application/xml' this receiver will only get message of CONTENT-TYPE 'application/xml'

 

Delete the listener

DELETE /topics/{topic-name}/durable/receivers/{receiver-id}