VM start action issues
by Tomas Von Veschler
Hi,
I'm unable to start a VM, this is what I get on both milestone 1 and 3:
POST
/rhevm-api-powershell/vms/28468e6d-8045-40bb-8c0e-543cec4d90ce/start
HTTP/1.1
Authorization: Basic cmhldmFkbWluOnJlZGhhdDEyMy4=
Host: rhevm:8443
Accept: application/xml
Content-type: application/xml
HTTP/1.1 400 Petición incorrecta
Server: Apache-Coyote/1.1
Content-Type: text/html;charset=utf-8
Content-Length: 1338
Date: Sun, 26 Sep 2010 13:18:13 GMT
Connection: close
<html>...
javax.xml.bind.UnmarshalException - with linked exception:
[org.xml.sax.SAXParseException: Premature end of file.]
Any ideas?
Thanks,
Tomas
13 years, 6 months
Representing the hierarchial nature of tags
by Mark McLoughlin
Hey,
Latest git contains a pretty complete implementation of tags, except for
representing the hierarchial nature tags
Here's how the concept works:
- A tag can have child tags
- If any of a childs' tags is applied to an object, then the parent
tag is also said to apply to the object[1]
- There is a 'root' pseudo-tag that applies to all objects
- The tags namespace is flat - you cannot have a 'bar' tag as a child
of 'foo' if a 'bar' tag exists elsewhere in the hierarchy
We had a few to consider when deciding how to model this in the REST
API:
1) Represent as a flat collection or as a hierarchy of collections
In the former option, we might just have a single tags collection
where each tag contains a reference to its parent tag
In the latter option, we'd represent child tags as a
sub-collection of each tag
2) Use <link rel="parent"/> or <parent><tag id="..."/></parent> to
reference a tags parent tag
3) Whether to represent the concept of the root tag as an actual
visible tag or just have make children of the root tag have no
parent in their representation
The crux of the issue turns out to be how best to represent using PUT to
move a tag around in the hierarchy.
i.e. you have a tag 'bar' (id=8) under tag 'foo' (id=0) and you want to
move 'foo' under the root tag (id=-1):
1) If we went with a hierarchy of collections, then the PUT request
would look like this:
PUT /tags/-1/tags/0/tags/8 HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<tag>
<parent><tag id="-1"/></parent>
</tag>
HTTP/1.1 200 OK
Content-Type: application/xml
<tag id="8" href="tags/-1/tags/8">
<name>foo</name>
<description></description>
<parent>
<tag id="-1" href="tags/-1"/>
</parent>
</tag>
What I really don't like is that the PUT causes the URI of the tag
to change. I guess we could use 'HTTP/1.1 301 Moved Permanently',
but ... ick.
Also, the URI structure is pretty disgusting.
2) If we used <link rel="parent"/> an update would look like:
PUT /tags/8 HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<tag>
<link rel="parent" href="tags/-1"/>
</tag>
HTTP/1.1 200 OK
Content-Type: application/xml
<tag id="8" href="tags/8">
<name>foo</name>
<description></description>
<link rel="parent" href="tags/-1"/>
</tag>
The problem here is that we don't allow updating a <link/> anywhere
else in the UI. Links are more for navigation rather than mutable
data.
3) If we didn't have an explicit resource representing the root tag,
the update would look like:
PUT /tags/8 HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<tag>
<parent><tag/></parent>
</tag>
HTTP/1.1 200 OK
Content-Type: application/xml
<tag id="8" href="tags/8">
<name>foo</name>
<description></description>
</tag>
That's not too bad, but I think it works better if you explicitly
reference the root tag.
After all that, the conclusion is to have a flat collection, use a
<parent/> element and have an explicit root resource. The update then
looks like:
PUT /tags/8 HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<tag>
<parent><tag id="-1"/></parent>
</tag>
HTTP/1.1 200 OK
Content-Type: application/xml
<tag id="8" href="tags/8">
<name>foo</name>
<description></description>
<parent>
<tag id="-1" href="tags/-1"/>
</parent>
</tag>
Thoughts?
Cheers,
Mark.
[1] - this seemed a bit backwards to me at first. I had assumed the
semantics to be that if a parent tag applies to an object, all child
tags also apply to the object. i.e. tags are more about what groups an
object is a member of rather than what groups an object is visible to
13 years, 7 months
Re: [rhevm-api] first diagram of RHEVM RESTful API.
by David Jorm
All the content authors within Red Hat use inkscape with a standard set of objects. All the official Red Hat documentation has diagrams drawn this way, with a common look and feel. For software engineering diagrams, inkscape is not the best tool, because it does not have standard UML shapes or any kind of round trip engineering. If you do want to use inkscape yourself, it would certainly make it easier to incorporate your diagrams into the docs. I would highly encourage you to do so if it meets your needs.
Some suggested labels for the boxes in the API diagram:
DataCenter/Cluster/Network: Logical Containers
Host/StorageDomain: Physical Resources
API/User/Role: [Security|Authentication|Authorization]
VmPool/Vm/Template: Virtual Machines
Let me know if you like these suggestions and i'll work them into the diagram.
As for the VirtualMachine diagram, I am not in a position to say which attributes are the 'foreign keys' so to speak. If you could draft something up first it would be helpful.
Thanks
David
----- Original Message -----
From: markllama(a)redhat.com
To: "David Jorm" <djorm(a)redhat.com>
Cc: rhevm-api(a)lists.fedorahosted.org, "Mark McLoughlin" <markmc(a)redhat.com>
Sent: Tuesday, September 21, 2010 10:03:40 PM GMT +10:00 Brisbane
Subject: Re: [rhevm-api] first diagram of RHEVM RESTful API.
----- "David Jorm" <djorm(a)redhat.com> wrote:
> I have created an inkscape diagram based on api.dia and incorporated
> it into the REST API Guide DocBook XML. The updates have been
> committed to git. Mark, could you please rebuild the version of guide
> the on the site?
>
> Unless anyone objects, I will proceed with modifying and incorporating
> the other diagrams...
>
Thanks David. I'm glad these could be of use.
I was intending to label the colored boxes in the API diagram, but I hadn't come up with good names yet. I'll look at Inkscape myself and may switch to using your diagrams as the base for anything I do. Dia does have convenient UML shapes, but having the diagrams in one canonical format is better I think, and if Inkscape is the common way, that works.
The other diagram needing some major work was the VirtualMachine one. It's way too busy. I want to remove most of the attribute information from the class boxes that doesn't relate directly to the relationships between the classes, and then create at least one new diagram highlighting the relationships between the VirtualMachine and the Template classes. and the components strictly in common.
I can take some time today to do that, or you can go ahead.
- Mark
13 years, 7 months
Re: [rhevm-api] first diagram of RHEVM RESTful API.
by David Jorm
I agree, these kind of diagrams would be a good enhancement to the official REST API Guide. The diagrams we use in the official docs are produced using a standard set of objects in inkscape. It would only take me a few hours to re-draw the diagrams in inkscape, and I think that would be a worthwhile effort. The only thing that concerns me is keeping the diagrams up to date. The existing PowerShell API docs are largely automatically generated from MAML. If the API is changed, I can point my script at the new MAML and it will modify the docbook automatically, leaving stubs where new commands or parameters need to be described. To the greatest extent possible, I would like to retain this capability with the new REST and Linux API Guides.
Any thoughts on how the diagrams could be automatically updatied, like they are in a round-trip-engineering CASE tool or something?
David
----- Original Message -----
From: "Mark McLoughlin" <markmc(a)redhat.com>
To: "Mark Lamourine" <mlamouri(a)redhat.com>
Cc: rhevm-api(a)lists.fedorahosted.org, "David Jorm" <djorm(a)redhat.com>
Sent: Friday, September 17, 2010 7:43:19 PM GMT +10:00 Brisbane
Subject: Re: [rhevm-api] first diagram of RHEVM RESTful API.
Hi Mark,
On Thu, 2010-09-16 at 10:35 -0400, Mark Lamourine wrote:
> Starting at the <api> tag and working my way down the tree.
>
> The groupings indicate what seem to be related objects as indicated by links and references in their schema elements listed in the RHEVM REST API doc 0.9. I'm going to try to diagram each of those boxes next to see if they are actually coherent.
>
> Note that the grouping resources are represented by the multiplicity associations rather than explicit objects.
>
> http://github.com/markllama/python-rhevmlib/blob/master/docs/Api.png
Interesting stuff; I see you've also created more detailed diagrams for
the resources themselves e.g.
http://github.com/markllama/python-rhevmlib/blob/master/docs/Hardware.png
I like the idea and wonder could we do something similar in the API
docs. David, what do you think? How could we best add something like
this to publican based docs?
Cheers,
Mark.
13 years, 7 months
Re: [rhevm-api] first diagram of RHEVM RESTful API.
by Mark Lamourine
----- "David Jorm" <djorm(a)redhat.com> wrote:
> I have created an inkscape diagram based on api.dia and incorporated
> it into the REST API Guide DocBook XML. The updates have been
> committed to git. Mark, could you please rebuild the version of guide
> the on the site?
>
> Unless anyone objects, I will proceed with modifying and incorporating
> the other diagrams...
>
Thanks David. I'm glad these could be of use.
I was intending to label the colored boxes in the API diagram, but I hadn't come up with good names yet. I'll look at Inkscape myself and may switch to using your diagrams as the base for anything I do. Dia does have convenient UML shapes, but having the diagrams in one canonical format is better I think, and if Inkscape is the common way, that works.
The other diagram needing some major work was the VirtualMachine one. It's way too busy. I want to remove most of the attribute information from the class boxes that doesn't relate directly to the relationships between the classes, and then create at least one new diagram highlighting the relationships between the VirtualMachine and the Template classes. and the components strictly in common.
I can take some time today to do that, or you can go ahead.
- Mark
13 years, 7 months
URL and resource names consistency (and relationships)
by Geert Jansen
Hi,
currently we have
GET /datacenters/xxx
200 OK
<data_center>
...
</data_center>
versus
GET /hosts/xxx
200 OK
<host>
</host>
i.e. there's an inconsistency between the resource types and the URLs
here (datacenter vs data_center).
Another type of (apparent) inconsistency is this:
GET /hosts/xxx/nics/yyy
200 OK
<host_nic>
...
</host_nic>
But it isn't really if you make a distinction between two types of
sub-collections:
i. "Existentially dependent" subcollections. This is relationship with a
cardinality of 1...1 - 0...n. The resources in the sub-collection cannot
exist without the parent resource. An example is the NIC of a host.
ii. "Linked" subcollections. This is a relationship with a cardinality
of 0...1 (or 0...n) - 0...m, i.e. both exist indepdendent of each other.
For example, a cluster and its hosts.
My feeling is that for i. you need to qualify the resource type of the
subcollection because it can't exist by itself. So e.g. "host_nic" or
"hostnic". While for ii. there is no need for qualification as there
presumably is another top-level collection that maps all the resources.
Elaborating on ii, this would also introduce a protocol to query linked
objects, e.g. "GET /clusters/xxx/hosts" and "GET
/datacenters/xxx/clusters". I'd go just one level deep. If you want to
get all VMs in a datacenter, that's two queries.
If you guys like this, then the "attachments" in datacenters could be
changed by a subcollection "storagedomains" for a datacenter. Right now
you're using an association resource "attachment" which is a bit ugly in
my view. Association resources are a necessary evil when the association
itself has attributes, but that's not the case here. In this case i feel
they are just a complication.
Regards,
Geert
13 years, 7 months
Action idiom
by Geert Jansen
Hi guys,
i had a go at the latest snapshot (snapshot3). I must say it looks
really good and you guys made tons of progress.
One thing that caught my attention is the actions protocol. I understand
that the fundamental difficulty that you're trying to solve is
shoehorning an RPC concept into a RESTful API. I struggled with that as
well when i wrote my API, and I haven't come to an ideal solution
either. That said, i think actions can be solved in a more RESTful way
than they are done now. It would be by using an "actions" subcollection,
where you POST an "action" object. Something like:
POST /hosts/123/actions
Content-Type: text/xml
<action>
<command>approve</command>
</action>
201 CREATED
It's not fully RESTful because only POST would be defined. (In theory it
would be possible to complement this with a full set of verbs making
"actions" fully RESTful. The semantics of the collection would be a set
of actions that have been executed for a resource. New actions posted
are executed automatically. Old actions are kept for reference and can
be retrieved. Note that this is a theoretical discussion as there is no
such thing as a log of actions in RHEV. The only thing this proves is
that this approach "quasi" RESTful :)
There's also the advantage that you've now disentangled the namespace
for actions and subcollections, and that you removed the "empty POST"
mechanism which is a bit ugly in my view.
I'm not saying these are make or break, but in my feeling it's a bit
cleaner this way. Just my 2 cents.
Regards,
Geert
13 years, 7 months
Re: [rhevm-api] Action idiom
by markllamai@redhat.com
----- "Eoghan Glynn" <eoghan.glynn(a)gmail.com> wrote:
> Hi Geert,
>
> Interesting idea.
>
> So for the sake of comparison, what we currently model as:
>
> POST /hosts/123/install
> Content-Type: application/xml
> <action>
> <root_password>geronimo</root_password>
> </action>
>
> you're suggesting we change to:
>
> POST /hosts/123/actions
> Content-Type: application/xml
> <action>
> <command>approve</command>
> <root_password>geronimo</root_password>
> </action>
>
I'm just starting to follow, but I was going to ask about action URIs myself. It would seem that the POST should go to the
object (resource) itself, and the method call and parameters would be described in the POST body.
I'd suggest something like this:
POST /hosts/123
Content-Type: application/xml
<action method="approve">
<param name="root_password">geronimo</param>
<!--... -->
</action>
There are models for this in XML-RPC already (Yes, that's XML RPC, but it's still applicable, I think).
It seems to me that object methods don't deserve a resource all their own. There should be a way to query the list of available actions on a resource (with their parameters and an indication of which are required or defaulted)
GET /hosts/123/actions
<actions>
<action method="">
<param name="" required="true|false" [default=""] />
...
</action>
...
</actions>
POST /hosts/123
...
<action method="">
<param name="">value</param>
...
</action>
An action is something you want the resource to do. The list of actions is something you want to ask for from the resource.
- Mark
13 years, 7 months
XML schema formats: Relax NG or XML Schema or....
by Mark Lamourine
In the process of learning about the RHEVM REST API I spend some time learning the XML schema for it. As an exercise, I've made a translation of the existing XML schema as defined in rhevm-api/api/src/main/resources/api.xsd to RelaxNG compact format.
In the process I re-organized the element definitions to group them by resource and their components where possible. I also added some commentary to help me understand components and their the relationships.
I've found indications that JAXB can use RelaxNG format (pure XML) with annotations as input but I don't know the status of that feature.
I used Trang to translate from RelaxNG Compact format (RNC) to RelaxNG XML format (RNG) and it appears that the annotations are maintained. The same is not true when converting from RNC to XML Schema (XSD)
Mark McLaughlin thought it might be useful to start a discussion of the merits of using RelaxNG as the canonical schema format. I find RNC very readable in a way that neither RNG or XSD are. However, if the tools don't support them well, then it could add more work than it's worth.
The translation is not yet complete and confirmed, so be kind. I've provided links to the two existing source candidates and I've attached the RNG and XSD translation from RNC for comparison.
Current XML Schema:
http://git.fedorahosted.org/git/?p=rhevm-api.git;a=blob;f=api/src/main/re...
RelaxNG Compact Schema:
http://github.com/markllama/python-rhevmlib/blob/master/lib/rhevm.rnc
Trang:
http://www.thaiopensource.com/relaxng/trang.html
JAXB RelaxNG Extension (experimental)
http://download.oracle.com/docs/cd/E17802_01/webservices/webservices/docs...
--- Translation CLI example ---
trang -I rnc -O rng lib/rhevm.rnc lib/rhevm.rng
trang -I rnc -O xsd lib/rhevm.rnc lib/rhevm.xsd
Mark Lamourine <markllama(a)redhat.com>
Sr. Software Developer, Cloud Engineering
Red Hat, 314 Littleton Road, Westford MA 01886
Voice: +1 978 392 1093
http://people.redhat.com/~mlamouri
markllama @ irc://irc.freenod.org*lopsa
13 years, 7 months
Re: [rhevm-api] Action idiom
by Mark Lamourine
> > There are models for this in XML-RPC already (Yes, that's XML RPC,
> but it's still applicable, I think).
>
> Mark,
>
> you should read an introductory text on REST :) I recommend some of
> Fielding's writings, for example this one:
>
> http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
I am just learning, thanks for the reference. So far I've been working with the two O'Reilly books: RESTful Web Services and Cookbook.
> REST is not RPC, on purpose. A POST on a collection has well-defined
> semantics: it should create a new resource inside the collection. So
> when POSTing to the "hosts" collection, the right semantics is that it
>
> should create a new host.
OK, I see that. I've also been reading (repeatedly) the RHEVM REST API spec and I'm making connections I'd missed with respect to how actions are presented and used. I'm coming around.
Resource R presents a set of actions as a list of resource references R/{actionname}. Any questions you have then about the actions should be answered by GET queries to those resources.
Got it. I'm ready to move on... Now, about those parameters...
- Mark
13 years, 7 months