RESTful QueueThis document is intended to document the ideal RESTful interface to message queues in light of Issues with Queues and RESTOne of the main issues with making a truly RESTful API to a message queue is that a message queue is essentially a load balancer, so each consumer of a queue sees essentially a different queue; as only one consumer gets a copy of each message. Also if a consumer goes away, the messages that were associated with that consumer need to be re-assigned to another consumer. So the main tricky part really is the operation for a consumer to find out what messages it may consume. Queue administrationThis section deals with the general browsing and creation/deletion of queues. Browse available queuesTo browse the queues, they are a hierarchial structure usually, so lets browse them like any APP collection GET /queues --------------------> 200 OK Atom Feed with one entry per directory/category/queue <-------------------- Browse a queue's messagesGET /queues/uk/products/books/computers --------------------> 200 OK Atom Feed with one entry per pending message <-------------------- Note that we could expose the queues as a tree, for example GET /queues/uk/products --------------------> 200 OK Atom Feed with one entry per queue in uk.products.* together with any child catgory/directory <-------------------- Creating a queueCreating a queue is typically idempotent; since really you are just creating a name that folks can post to. POST /queues --------------------> 201 OK Location: someUniqueUrlForTheNewQueueToBePostedTo <-------------------- Deleting a queueDELETE /queues/foo.bar --------------------> 200 OK <-------------------- Send to queueSending to queue is the usual APP-style double request; one to get the unique URI to post to and secondly to do the actual post... POST /queues/foo.bar --------------------> 201 OK Location: someUniqueUrlForTheNewMessageToBePostedTo <-------------------- The client can then repeatedly POST the mesage to someUniqueUrlForTheNewMessageToBePostedTo until it gets a 200 OK which avoids duplicates. Optional alternative for single requestIf a smart client is capable of generating a system wide unique GUID (id) for the message, the server side could ignore duplicates. So posting to queue could be done without the double-request approach above POST /queues/foo.bar?guid=clientGeneratedUniqueId --------------------> 200 OK <-------------------- Consuming from a queueAs described above, this is the tricky part of mapping message queues to REST. So we introduce a resource for a subscription to a queue. The subscription remains active until some timeout value - so a subscription is a sort of lease. When a subscription is created it can be given a variety of different pieces of data such as
Create a subscriptionPOST /subscriptions --------------------> 201 OK Location: subscriptionUri <-------------------- The actual subscription data could be form encoded key/value pairs. Deleting a subscriptionGood clients will delete subscriptions when they are no longer required; though they do timeout eventually. DELETE subscriptionUri --------------------> 200 OK <-------------------- Consuming messagesYou consume messages by browsing the subscription (like any APP resource) then DELETEing the message when you have finished processing it. GET subscriptionUri --------------------> 200 OK Atom Feed with one entry per message associated to this subscription <-------------------- Then to acknowledge a particular message has been processed DELETE messageUri --------------------> 200 OK <-------------------- Deltas with APPAlmost all of the above could be just pure APP really. The only real difference is that each consumer has its own feed of messages which are to be consumed. In ActiveMQ's case, we use a prefetch value per consumer to define how many messages each consumer gets in its buffer, before messages must be acknowledged to get more messages. So the idea is that we have a per-consumer feed which is created; it can then be browsed (by anyone with sufficient karma). |