IWHD API Suggestions

Michal Fojtik mfojtik at redhat.com
Tue Sep 13 17:15:13 UTC 2011


On Sep 6, 2011, at 5:42 PM, Martyn Taylor wrote:

I recently found this project from Geert Jansen:

http://restful-api-design.readthedocs.org/en/latest/index.html

Include a tons of useful informations about REST API design.

 -- michal

> Over the last few months; we (the aeolus team) have come across a few 
> difficulties when integrating with IWHD API and are hoping we can get 
> some changes into the app to make life a little easier for us.  I've put
> together a list of things that could be changed that would drastically 
> help our integration.
> 
> So firstly, we hope that IWHD can provide a typical RESTful API, so that 
> we can consume it using  standard libraries that consume REST interfaces.
> 
> The first three suggestions are aimed towards this.
> 
> 1) XML Element Tags
> 
> Element Tags should map to the resource type.  At the moment the root 
> element for all resources and collections is <object(s)>.
> 
> 2) REST Metadata Tags
> 
> We should use the defined METAdata tags for defining resource relations, 
> ids, and resource location.  The typical way to achieve this for XML is 
> to use link elements to represent relations and id and href attributes 
> in the root element of the resource.
> 
> e.g.
> 
> <image id="1234" href="http://localhost:9090/images/1234">
> <link href="http://localhost/builds/1234"/>
> </image>
> 
> 3) Discoverable API
> 
> One of the REST constraints is that the API should be discoverable and 
> the client need not know any thing more than the root url or the 
> application.  When navigating to IWHD API, its possible to get as far as
> a single resource for each collection only.
> 
> Moving all of the stuff under _attrs into link elements on the resource 
> should fix this.
> 
> Other Improvements
> 
> 4) Relationships
> 
> This may also be a constriant of REST.  Though I'm not 100%
> 
> Anyway, One of the main problems we are having is that relations are 
> added to child objects only.  For example, the Build object holds a 
> reference to its Image relation, but Image does hold references for its
> Build relations.
> 
> We generally navigate through the object model from top level down.  In 
> order to do this we are having to search over all the child objects to 
> look for the parent relation.  For example, say we need a list of Build
> for a particular Image, we need to search over all* Build objects, and 
> look to see if its ImageID matches.  This results in issuing a lot of 
> requests to get the right data, this is time consuming.
> 
> It would be extremely beneficial to us, if iwhd stored two way 
> relations, so that parent objects had a list of its children, as well as 
> the child containing the parent object.
> 
> 
> _______________________________________________
> aeolus-devel mailing list
> aeolus-devel at lists.fedorahosted.org
> https://fedorahosted.org/mailman/listinfo/aeolus-devel

------------------------------------------------------
Michal Fojtik, mfojtik at redhat.com
Deltacloud API: http://deltacloud.org



More information about the iwhd-devel mailing list