On Tuesday, August 07, 2012 02:32:14 PM Martyn Taylor wrote:
On 08/07/2012 08:30 AM, Petr Blaho wrote:
On Monday, August 06, 2012 05:06:25 PM Richard Su wrote:
On 08/06/2012 07:59 AM, Dave Johnson wrote:
On Mon, 2012-08-06 at 09:44 -0400, Michael Orazi wrote:
----- Original Message -----
Hi Dave,
I started a wiki page here:
https://www.aeolusproject.org/redmine/projects/aeolus/wiki/Pools
This is a rough outline. One of the things I'm wondering about is
whether the request data should be in xml or be in http parameters.
It
feels to me parameters may be easier to work with as you are
essentially
stuffing them into an array. It's not clear to me if there is a
rails
standard for xml or parameters. AWS uses parameters whereas RHEV REST
API uses xml.
Do you see an advantage of using one or the other? In the outline I
have
the requests written to use xml.
Thanks,
Richard
Adding Martyn & Jay to the cc list as they may have some insight into the broader
RESTful api discussion/rails best practices, etc.
m
Hey Richard,
This is a great start for the story and I thank you for taking the time
to document this up front. The only "advantage" I can think of is
consistency with the provider/account api. It is using xml. And
correct me if I am wrong but I believe the image build/push calls do as
well?
-Dave
Being consistent is good. Right now, I don't think provider/account api
is xml based though. Supporting xml adds some overhead. The client has
to generate xml and the controller has to parse it. Posting query
parameters require fewer changes to existing controller logic.
Right now provider/account API uses XML.
There is really no overhead i controllers w/r/t amount of code written.
Just use --header "Content-Type: application/xml" in curl and rails translates
nodes and attributes to params hash.
This --header should be used whenever posting XML to rails app.
For pools. I think I'll set it up to do both. And then people can review
and weigh in on which way to go.
If there is no differencies in how parameters are nested (XML vs parameters)
theese can be both available at the same time with almost no effort.
This applies to request data. Adding support for these in response data too is a little
trickier. For the reasons I posted on the list a while back on why we use templates.
adding Petr to the discussion.
- Richard
I just started wiki pages for Provider and Providr Accounts API -
https://www.aeolusproject.org/redmine/projects/aeolus/wiki/Providers ,
https://www.aeolusproject.org/redmine/projects/aeolus/wiki/Provider_Accounts
Hey Richard. Great start on this. I've a couple of comments below in on form-data
and your current doc.
I would avoid using x-ww-form-urlencoded for representing resources. XML and JSON allow
you to create structured documents in a standard way. Trying to add things like nested
resources using key/value pairs is difficult and would require us to create our own way of
handling such things. This would mean that clients would also need to written
specifically for our API. XML and JSON have a ton of support for marshalling and
unmarshalling objects in plenty of languages. Representations in these are also much more
readible than an enocded string these two alsooffer some form of typing for example,
arrays. Since we already support XML in a number of areas of Conductor API and in the
CLI. We should stick with this for the time being then maybe introduce JSON support
later.
Also I noticed a few things with your documentation.
Why are you using url attribute. We use href (stolen from html spec) to point to resource
locations in other parts of the API: see the original API doc I wrote a while back:
https://www.aeolusproject.org/redmine/projects/aeolus/wiki/Conductor_API
I'm not sure if rails requires it. But you should set the content-type header when
sending data. In theory you could send XML and ask for JSON.
We should be using PUT verb for updates. The documentation says you are using POST. See
spec:
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
There is a mistake in some of the XML. The enabled element is not closed properly.
<pool id="1" url="https://localhost/conductor/api/pools/1">
<name>pool1name</name>
<pool_family id="1"
url="https://localhost/conductor/api/pool_families/1">pool family 1
name</pool_family>
<quota></quota>
<enabled>true</name>
<deployments></deployments>
</pool>
Thanks
Martyn
Just CCed aeolus-devel list. I think this is quite interesting for all developers there.
--
With regards
Petr Blaho