Re: [rhevm-api] REST API docs
by David Jorm
Good job, Mark! A couple of comments:
- The current Powershell API docs are command-oriented. Each command has a section in the docs detailing its syntax and providing usage examples. The commands are grouped by their functionality. Each of the classes exposed in the API (as return values from the commands) are detailed in a separate reference section. What you've generated seems to be class/object/entity/whateveryoucallit oriented, rather than command oriented. I don't have a problem with this, but if we were to move the official docs to this structure it would need wider discussion. It does seem like the logical way to go based on the way the new API works, but my understanding is we will also have Powershell and Linux shell wrapper APIs, which may force a more command oriented structure for the documentation.
- The basic syntax of the Powershell API is documented by the developers using MAML (http://en.wikipedia.org/wiki/Microsoft_Assistance_Markup_Language). This includes description strings against commands and their parameters. The MAML is used by Windows to provide online help and results from the Get-Help command. The DocBook based official documentation is largely automatically generated from the MAML. Will there be any analogous internal documentation for the new API which could serve as a basis for the official docs?
Thanks
David
----- Original Message -----
From: "Mark McLoughlin" <markmc(a)redhat.com>
To: "rhevm-api" <rhevm-api(a)lists.fedorahosted.org>
Sent: Thursday, April 8, 2010 3:33:33 AM GMT +10:00 Brisbane
Subject: [rhevm-api] REST API docs
Hi,
I've made a first attempt at documenting the REST API here:
https://fedorahosted.org/rhevm-api/wiki/ApiReference
https://fedorahosted.org/rhevm-api/wiki/VirtualMachinesCollection
Basically, I just wanted to get a feel for how sane the semantics sound
when described in prose. It seems like a fine start to me?
Geert will notice that I borrowed liberally from his API reference
style :-)
Thanks,
Mark.
_______________________________________________
rhevm-api mailing list
rhevm-api(a)lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/rhevm-api
14 years, 1 month
Long-running search queries
by Eoghan Glynn
Hi Folks,
I've been chewing away on that asynchronous VM query notion, seeking a
RESTful interaction that's both simple and scalable.
One thought was to achieve this by combining a synchronous query-constrained
GET providing a baseline, with intermediate updates supplied via a generic
Atom feed, supplemented by query-specific filtering on the client-side.
So on startup, or intermittently with low frequency, the client executes a
GET constrained by the particular query its current interested in (e.g. user
= joe AND status = Up). Roughly speaking, something like:
GET /vms
Content-Type: application/vnd.org.redhat.rhevm.api.Query+xml
Accept: application/vnd.org.redhat.rhevm.api.VMs+xml
<query>
<and>
<user>joe</user>
<status>Up</status>
</and>
</query>
200 OK
Content-Type:application/vnd.org.redhat.rhevm.api.VMs+xml
Date: timestamp.for.subsequent.If-Modified-Since
<vms>
<vm>
<user>joe</user>
<name>vm001</name>
...
</vm>
<vm>
<user>joe</user>
<name>vm002</name>
...
</vm>
...
<vm>
<user>joe</user>
<name>vm999</name>
...
</vm>
*<link rel="updates" type="application/atom+xml" href="
http://host.rhevm/vms/notify"/>
*</vms>
The client then consumes the "updates" feed and uses this to reconcile the
initial baseline it received with subsequent changes to the population of
VMs. In order to ensure that the updates only include genuinely fresh data,
the feed could be polled via a conditional GET (based on If-Modified-Since
with the timestamp of the previous full GET /vms or the last GET
/vms/notify, whichever is the later). In general the number of updated VMs
will be small compared to the size of the entire collection, making it
feasible for filtering to be applied on the client side as each entry in the
feed is dereferenced. In order to scale well, the Atom feed would probably
have to be non-query specific (i.e. the same for all clients), hence the
need for client-specific filtering implemented on the client itself via
XPath or somesuch.
In the pathological case where there's an episode with lots of churn in the
VM population, say with a large number of VMs being rebooted concurrently,
then the client could simply move on its baseline with a repeated "GET /vms"
and then start over afresh. Deciding when to do this could be based on a
heuristic involving the number of entries in the Atom feed versus the size
of the original VM collection.
The main advantage of this approach would be to keep the interaction *
stateless*, while avoiding tying up a connection per-client with long
polling for async search results. So rather than having to manage a
search-session lifecycle, each client's interaction (the original "GET /vms"
and the subsequent Atom feed retrieval) is driven by state held solely on
the client side.
One further advantage of leveraging the standard Atom representation would
be to open up the feed part of the interaction to a wide class of generic
clients.
One disadvantage is that the client becomes necessarily more complex to
handle feed filtering, though the Atom aspect could be seen as an
optimization strategy that not all clients would have to adopt (a simple
script, say, could use only the basic "GET /vms" approach, whereas an
AJAX-based UI would go the full nine yards).
Feedback welcome ...
Cheers,
Eoghan
14 years, 1 month
The case for REST?
by Mark McLoughlin
Hi,
I've been reading about REST and trying to put together a convincing
list of reasons why we should choose it over SOAP:
- There's a lot of buzz about it right now - twitter, flickr,
facebook, S3, deltacloud etc. are all basing their APIs on it[1]
- RHEV-M runs on JBoss and there's a significant REST push in the
JBoss community (lead by Bill Burke) with RESTeasy, REST-* etc.
- It makes APIs very easy to understand and play with - just look at
some of the popular RESTful APIs ... you could imagine doing
something fun with them after 5 minutes hacking
- A RESTful API is largely self describing - e.g. the XML/JSON
representation of a VM would include links for each VM action
available
- In theory, there should be less interoperability issues because of
the simplicity
- Resources are addressable - you can imagine all sorts of
interesting possibilities from being able to pass around a URL for
a VM, for example
- Easier to consume RESTful APIs in AJAX apps
And then there are a whole heap of advantages REST advocates shout about
which I'm finding hard to get excited/convinced by:
- Because you're not abusing HTTP as a transport protocol, standard
HTTP constructs can be used - caching, proxies, gateways etc.
- The web scales really well, so RESTful APIs will naturally scale too
And some disadvantages:
- At first, it looks trivial to design a good RESTful API ... but the
more I read, the more really subtle issues[3] there are to think
about - you only need to look at all the controversies about
various APIs being denounced as not truly RESTful
- Similarly, what we essentially want is an RPC API, but thinking
about REST as just another API protocol almost guarantees you'll do
it wrong
- It doesn't look like there is the same level of auto-generated
client bindings available as there is with SOAP/WSDL[4]
Perhaps it's just a case of being turned off REST by the elevated levels
of hype and the angst-ridden battles going on over just what is and
isn't RESTful[5]
Cheers,
Mark.
[1] - Well, they claim to be - and then at least some of them are
denounced as being not "truly" RESTful
[2] - Nice where certain actions are only available to certain users,
now thank I think about it
[3] - Simple example - POST apparently should be idempotent, so for the
"create VM" API, do you require the client to generate an ID and ensure
reject multiple requests with that API e.g.
=> POST /vms/
<vm>
<id>XXX-XXX-XXX</id>
<name>foo</name>
</vm>
or do you have POST generate an ID, which you then PUT to:
=> POST /vms/
<= HTTP/1.1 200 OK
Location: /vms/XXX-XXX-XXX
=> PUT /vms/XXX-XXX-XXX
<vm>
<name>foo</name>
</vm>
[4] - Although ... my guess is the auto-generated bindings are never
that nice and wrapping the auto-generated binding with a more natural
API for the language would be a similar job as wrapping a REST API
[5] - e.g. I find it very hard to see why I should care about most of
the points here:
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
14 years, 1 month