The links for operations look good - a simple HTTP POST to a straight url.
I didn't think there would be much contention here. I'm surprised I didn't get more abuse about using UUID4's but that's a no brainer when you understand the concurrency issues (and don't want to expose any secrets, particularly about the size of your operation). I'm certainly not the first to do this either.
I'm more concerned about the Atom XML. I agree that what you've done is a
decent implementation of standard Atom XML, but am worried about the amount
of overhead which this has introduced.
When you get down to the details (as I did over the weekend) you'll see that Atom fits like a glove for this purpose and gives us many things for free (like tagging, categories and embedding of arbitrary content types like OVF) that we would otherwise have to implement ourselves. It also critically provides a clean, simple way to link between resources and specify attributes on the links themselves (e.g. network X is connected to virtual machine Y on interface eth0).
Looking at the sample code on the wiki at present, this is currently 2778
characters spread over 53 lines, using 5 xml namespaces and around 20-30 xml
tags with up to 7 levels of indentation. And it's explicitly abbreviated
with a '...'.
Right, sure XML is more verbose. It's also easy to extend, sign, encrypt and perhaps most importantly, validate. I actually think Atom is a nice middle ground between mickey mouse plain text APIs and WS-[death]star. As a bonus it seamlessly and transparently allows demanding enterprise users to transport whatever esoteric XML-based SLAs and other cruft they like. We can also natively support (or at least transport) OVF too which I think will be increasingly important for interoperability.
What this code actually does is return a handful of details about a single
virtual machine. If I only list the actual data fields then we have:
<server>
<id>decca5a5-8952-4004-9793-cdbbf05c3c63</id>
<title>Debian GNU/Linux 5.0 Virtual Appliance</title>
<summary>Base installation of Debian GNU/Linux 5.0</summary>
<cpu>2</cpu>
<mem>4Gb</mem>
<disk id="file1" href="virtual-disk.vmdk" size="148251374"/>
<nic>2</nic>
<state>RUNNING</state>
<meter rate="0.10" currency="USD" unit="hours">35.27</meter>
<monitor type="cpu">75.2%</monitor>
<monitor type="mem">1059374258</monitor>
<storage id="4696b561-a253-42b4-bd27-7aa4950e0a60"/>
<network id="45a73b80-c957-4ae1-97c6-b70652eba1d1"/>
</server>
That's 575 characters over 15 lines with 14 tags in 1 namespace and 1 level
of indentation. It is now simple enough that I could trivially parse it or
generate it from any programming language without any libraries if
necessary. The equivalent JSON is also obvious and simple.
Right, and when someone adds a "flux capacitor" to the list of available resources we need to go back to the drawing board (or they'll just add it themselves and we're back to the old embrace and extend approach). I envisage that we could [have IANA] maintain a similar registry of resource types as they do for
link relations, but I think the need for such a thing will become clearer as we delve further into the problem.
Both the ElasticHosts and GoGrid APIs are written much more in this second
style of syntax - which is what we mean by a "design pattern B" - work out
exactly what data is needed for each operation and write down exactly this
with the absolute minimum of syntax overhead.
Sure, and you'll get that too. Let me whip up some examples to go alongside the XML.
Sam