outline of pools api requests and responses

Petr Blaho pblaho at redhat.com
Tue Aug 7 13:46:53 UTC 2012


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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fedorahosted.org/pipermail/aeolus-devel/attachments/20120807/adce79f2/attachment.html>


More information about the aeolus-devel mailing list