Return-Path: 
 <users-return-11135-apmail-qpid-users-archive=qpid.apache.org@qpid.apache.org>
X-Original-To: apmail-qpid-users-archive@www.apache.org
Delivered-To: apmail-qpid-users-archive@www.apache.org
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
	by minotaur.apache.org (Postfix) with SMTP id 27A9E1170E
	for <apmail-qpid-users-archive@www.apache.org>;
 Wed,  3 Sep 2014 21:51:57 +0000 (UTC)
Received: (qmail 90168 invoked by uid 500); 3 Sep 2014 21:51:52 -0000
Delivered-To: apmail-qpid-users-archive@qpid.apache.org
Received: (qmail 90133 invoked by uid 500); 3 Sep 2014 21:51:52 -0000
Mailing-List: contact users-help@qpid.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:users-help@qpid.apache.org>
List-Unsubscribe: <mailto:users-unsubscribe@qpid.apache.org>
List-Post: <mailto:users@qpid.apache.org>
List-Id: <users.qpid.apache.org>
Reply-To: users@qpid.apache.org
Delivered-To: mailing list users@qpid.apache.org
Received: (qmail 90109 invoked by uid 99); 3 Sep 2014 21:51:51 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 03 Sep 2014 21:51:51 +0000
X-ASF-Spam-Status: No, hits=-5.0 required=5.0
	tests=RCVD_IN_DNSWL_HI,SPF_HELO_PASS,SPF_PASS
X-Spam-Check-By: apache.org
Received-SPF: pass (athena.apache.org: domain of aconway@redhat.com designates
 209.132.183.28 as permitted sender)
Received: from [209.132.183.28] (HELO mx1.redhat.com) (209.132.183.28)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 03 Sep 2014 21:51:46 +0000
Received: from int-mx09.intmail.prod.int.phx2.redhat.com
 (int-mx09.intmail.prod.int.phx2.redhat.com [10.5.11.22])
	by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s83LpOl9029533
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL)
	for <users@qpid.apache.org>; Wed, 3 Sep 2014 17:51:24 -0400
Received: from [10.3.113.60] (ovpn-113-60.phx2.redhat.com [10.3.113.60])
	by int-mx09.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id
 s83LpNYD007887
	for <users@qpid.apache.org>; Wed, 3 Sep 2014 17:51:24 -0400
Message-ID: <1409781083.6758.35.camel@localhost>
Subject: Re: REST API for AMQP management?
From: Alan Conway <aconway@redhat.com>
To: users@qpid.apache.org
Date: Wed, 03 Sep 2014 17:51:23 -0400
In-Reply-To: 
 <CACsaS97anp9_jkTPR6taP198Quz7s19muPoVR7Nw1EoNqm_iUA@mail.gmail.com>
References: <1409341222.13978.4.camel@localhost>
	 <D026422F.32AC4%jagibson@ebay.com> <1409345959.13978.30.camel@localhost>
	 <CACsaS9647wmnCDhL1B1Nj3xXOoWZNZqTTOm99_s-zL2_=AniUg@mail.gmail.com>
	 <1409347493.13978.36.camel@localhost>
	 <CACsaS94C+v5kgJNnktZk4KoUcWgub21hpb24V7YQi=5ciiBTSw@mail.gmail.com>
	 <CACsaS97anp9_jkTPR6taP198Quz7s19muPoVR7Nw1EoNqm_iUA@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"
Mime-Version: 1.0
Content-Transfer-Encoding: 8bit
X-Scanned-By: MIMEDefang 2.68 on 10.5.11.22
X-Virus-Checked: Checked by ClamAV on apache.org

On Fri, 2014-08-29 at 23:58 +0200, Rob Godfrey wrote:
> So, the other aspect that could be considered in a REST API is whether the
> type should form part of the URI.  The REST API URIs of both RabbitMQ and
> the Java Broker look something like /api/<type>/<name-path>.  So for
> instance a queue might be addressed by /api/queue/myvhost/myqueue.  This
> also allows for the expected behaviour of /api/queue/myvhost to bring back
> the collection of all "queue" objects on the virtualhost vhost.  If we
> think of this as being /api/<type>/<name> in an AMQP management sense then
> it would lead to the conclusion that when viewed at the level of a broker
> which has multiple virtual hosts a queue name might be considered to be
> "<virtualhostname>/<queue name>" whereas if the management operation was
> constrained to viewing only a single virtual host then the "name" observed
> at that management node would simply be "<queue name>".
> 

My reading of the management spec is that entity names and ids are
unique across all entities, not just across a type, so the type would be
redundant. You might want to query for an entity by name/id when you
don't know its type. I'm not dead set against including the type, just
not sure if it's the Right Thing. 

You could query differently e.g. /api/query?type=queue
which would perhaps map more naturally onto AMQP management queries
which are a map of optional query parameters rather than a sequential
path.

As to virtual hosts, the C++ broker doesn't even have them so I would
think they are an (optional) part of the entity name that is interpreted
by the broker as appropriate.

> On 29 August 2014 23:35, Rob Godfrey <rob.j.godfrey@gmail.com> wrote:
> 
> > My expectation (and the way the Java Broker works) is that the ID may well
> > be a UUID... this doesn't make for a terribly easily human readable URI.
> > The expectation is that the ID is generated by the server.  This doesn't
> > play terribly well with REST where the creation of the resource would be at
> > the location given in the URI which would make it user rather than server
> supplied.

We should let the user create an entity with a management name which is
user-specified. They can get the generated ID from the response. Since
we can't assume names and IDs won't clash it seems to me we need name
URIs and ID URIs. So you would create a new entity with URI like:

/api/name/foo

and get a response which includes "id=horribleServerGeneratedId". Then
you could query the entity using either of:

/api/name/foo
/api/id/horribleServerGeneratedId

I'm new to thinking about REST so all of the above is subject to change
when someone patiently explains things to me.

> > On 29 August 2014 23:24, Alan Conway <aconway@redhat.com> wrote:
> >
> >> On Fri, 2014-08-29 at 23:09 +0200, Rob Godfrey wrote:
> >> > Can you give an example of how you would create / read / update /
> >> delete a
> >> > named object of a given type through this API.
> >> >
> >> > Are you using the name or the identity field as the identifier to
> >> generate
> >> > the URI for the "resource" being described?
> >>
> >> I am assuming some fairly straightforward conversion between AMQP
> >> Management messages and HTTP requests. My first thought is to use JSON
> >> but there may be other more appropriate serializations. I would be
> >> inclined to use identity for the URI.
> >>
> >> I find the name/identity duality in AMQP management to be a serious
> >> pain. I would get rid of name. We need an immutable identity for every
> >> object. If some objects also need a mutable name, just give them an
> >> attribute "name". If you want to be able to search by name, then
> >> introduce a "query by attribute value" that would be more generally
> >> useful than for just name attributes. That would make the spec simpler
> >> and more powerful.
> >>
> >> Cheers,
> >> Alan.
> >>
> >> >
> >> > -- Rob
> >> >
> >> >
> >> > On 29 August 2014 22:59, Alan Conway <aconway@redhat.com> wrote:
> >> >
> >> > > On Fri, 2014-08-29 at 19:45 +0000, Gibson, Jack wrote:
> >> > > > Alan -
> >> > > >
> >> > > > I have been playing with vertx to amqp 1.0 set of restful services
> >> to
> >> > > > manage dispatch routers.  So, I wouldn¹t mind helping out.  Let me
> >> know
> >> > > to
> >> > > > engage.
> >> > > >
> >> > >
> >> > > I've been distracted for a while so I need to get my head back into
> >> the
> >> > > dispatch management code. I have some work to finish up, mostly
> >> merging
> >> > > functionality from the old C agent into the new python agent.
> >> > >
> >> > > The python agent is basically a schema validater and dispatcher of
> >> AMQP
> >> > > management requests into the C code. The management requests and
> >> > > responses are essentially just name/value maps or lists of maps. The
> >> > > type system is simple for now: strings, bools, integers and floats. I
> >> > > doubt it will get much more complicated than that.
> >> > >
> >> > > So I think for REST all we need is a HTTP server (presumably the
> >> default
> >> > > python one would do) that converts HTTP requests to and from a
> >> > > router.Message with python maps as properties and body. The management
> >> > > code is already quite JSON friendly so that might be an easy way to do
> >> > > it.
> >> > >
> >> > > Have a look at
> >> > > dispatch/python/qpid_dispatch_internal/management/agent.py
> >> > >
> >> > > Agent.receive() is wired up to get AMQP management messages. It calls
> >> > > Agent.handle() to process the message, and returns an AMQP response.
> >> > >
> >> > > The REST listener would be similar to receive() - create a request
> >> from
> >> > > the HTTP request, feed it to Agent.handle() and convert the response
> >> to
> >> > > a HTTP response.
> >> > >
> >> > > We can tidy things up a bit to make a clean interface between REST,
> >> AMQP
> >> > > messages and whatever other feeds might come along and a more generic
> >> > > Agent. With a clean API we should be able to re-use the same REST code
> >> > > for inside dispatch, in your vertx services, or as a stand alone tool
> >> > > that converts between REST and AMQP, or in tools for managing Qpid or
> >> > > other AMQP services. I want to separate and make public the AMQP
> >> > > management client for scripting, so that could be the basis of a
> >> > > stand-alone REST to AMQP gateway.
> >> > >
> >> > > Let me know what you think!
> >> > > Cheers,
> >> > > Alan.
> >> > >
> >> > >
> >> > >
> >> > > ---------------------------------------------------------------------
> >> > > To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
> >> > > For additional commands, e-mail: users-help@qpid.apache.org
> >> > >
> >> > >
> >>
> >>
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
> >> For additional commands, e-mail: users-help@qpid.apache.org
> >>
> >>
> >



---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org