[rabbitmq-discuss] RabbitMQ HTTP interface

[Tony Garnock-Jones]

Hi,

lenz wrote:
> from the javascript client that comes with the rabbit-http2 repo i kind
> of got an idea how things are supposed to work but i wanted to ask if
> there is some sort of documentation/API description around that i could
> use to implement a client from?

I can think of a few things to get you started -- and BTW this sounds
like a really interesting project, do keep us up-to-date with your
progress as you go!

1. The service is standard JSON-RPC 1.1 (see spec mirrored here:
http://hg.opensource.lshift.net/erlang-rfc4627/raw-file/default/doc/JSON-RPC-1-1-WD-20060807.html).
You can probably use an off-the-shelf JSON-RPC client library.

2. There is plenty of documentation on the Erlang JSON-RPC service that
the RabbitMQ HTTP2 adapter uses here:
http://hg.opensource.lshift.net/erlang-rfc4627/raw-file/default/doc/index.html

3. The service descriptions (see the JSON-RPC 1.1 spec, §10) are as follows:

* The channel factory at .../rpc/rabbitmq:

{
    "sdversion":"1.0",
    "name":"rabbitmq",
    "id":"urn:uuid:f98a4235-20a9-4321-a15c-94878a6a14f3",
    "version":"1.2",
    "address":"http://rabbitmq.lshift.net:55672/rpc/rabbitmq",
    "procs":[{"name":"open","idempotent":false,
	      "params":[{"name":"username","type":"str"},
			{"name":"password","type":"str"},
			{"name":"sessionTimeout","type":"num"},
			{"name":"virtualHost","type":"str"}]}]
}

* Each individual channel, at .../rpc/SOMEUNGUESSABLEHEXIDENTIFIER:

{
    "sdversion":"1.0",
    "name":"B10D3152ED205726DC3A8EF03FD00C7B",
    "id":"urn:uuid:b3f82f69-4f63-424b-8dbb-4fa53f63cf06",
    "version":"1.2",

"address":"http://rabbitmq.lshift.net:55672/rpc/SOMEUNGUESSABLEHEXIDENTIFIER",
    "procs":[{"name":"poll","idempotent":false,
	      "params":[]},
	     {"name":"close","idempotent":false,
	      "params":[]},
	     {"name":"call","idempotent":false,
	      "params":[{"name":"method","type":"str"},
			{"name":"args","type":"arr"}]},
	     {"name":"cast","idempotent":false,
	      "params":[{"name":"method","type":"str"},
			{"name":"args","type":"arr"},
			{"name":"content","type":"str"},
			{"name":"props","type":"arr"}]}]
}

The "poll" method returns details of all the asynchronous events that
have arrived for the channel -- the basic.delivers, the basic.returns.

The "close" method is used to shut down the channel.

The "call" and "cast" methods are used to perform synchronous (e.g.
exchange.declare) and asynchronous (e.g. basic.publish, basic.ack) AMQP
operations, respectively.

"call" returns the response to the synchronous call.

"cast" returns a list of asynchronous events that had been queued up at
the server-side of the Channel, *just like poll does*. So both poll and
cast can return deliveries intended for your program!

See rabbitmq.js's definitions of such as basicPublish() and
exchangeDeclare() for examples of usage.


Here's a login call (to .../rpc/rabbitmq):

REQUEST:
{"version":"1.1","id":2,"method":"open","params":["guest","guest",5,null]}

RESPONSE:
{"version":"1.1","id":2,"result":{"service":"SOMEUNGUESSABLEHEXIDENTIFIER"}}

Then, in the URL you're using to access the channel-opening service
(i.e. .../rpc/rabbitmq), replace "rabbitmq" with the "service" result
parameter, yielding .../rpc/SOMEUNGUESSABLEHEXIDENTIFIER. This is the
URL for your channel object. You use this to begin subscriptions and
issue AMQP commands.

Here's a queue declaration:

REQUEST:
{"version":"1.1","id":6,"method":"call","params":["queue.declare",[1,"test-queue-1a",false,false,false,true,false,{}]]}

RESPONSE:
{"version":"1.1","id":6,"result":{"method":"queue.declare_ok","args":["test-queue-1a",0,0]}}

Here's a use of "cast":

REQUEST:
{"version":"1.1","id":10,"method":"cast","params":["basic.publish",[1,"","test-queue-1a",false,false
],
"hello, world",
[null,null,null,null,null,null,null,null,null,null,null,null,null,null]]}

RESPONSE:
{"version":"1.1","id":10,"result":[{"method":"basic.deliver","args":["aa-cons-tag1",1,false,"","test-queue-1a"
],"content":"hello,
world","props":[null,null,null,null,null,null,null,null,null,null,null,null,null
,null]}]}

Note how the "result" array is non-empty, and that RabbitMQ is quick
enough that by the time the JSON-RPC object is ready to return to its
caller, the method that was just published has already been delivered :-)

Generally, for method arguments, follow the definitions given in the 0-8
json document:
http://hg.rabbitmq.com/rabbitmq-codegen/raw-file/default/amqp-0.8.json

Hopefully that is enough to get you started!

Regards,
  Tony
-- 
 [][][] Tony Garnock-Jones     | Mob: +44 (0)7905 974 211
   [][] LShift Ltd             | Tel: +44 (0)20 7729 7060
 []  [] http://www.lshift.net/ | Email: tonyg at lshift.net