Morning Sam! Thanks for your latest mail, and the work that you have clearly put in to get some examples, XSLT, etc. up. Here's the ElasticHosts view:
Amazon use a simple but sprawling XML based API ... there are a raft of intellectual property issues as well:
We definitely agree with you that OCCI can produce a better API than Amazon, both in terms of IP issues and also a cleaner design. If I were Amazon and wanted to play hardball, I would (a) allow Eucalyptus, etc to copy my API for now (since it only helps me gain traction as a defacto standard), (b) remain vague about IP for now, (c) not support any other API standards while I remember the defacto standard and (d) later halt or charge fees to any competition which becomes serious. (a), (b) and (c) seem well executed to date ;-)
I am now 100% convinced that the best results are to be had with a variant of XML over HTTP ... support alternative formats including HTML, JSON and TXT via XML Stylesheets
As you're well aware, we're less in favour of XML. However support for alternative formats with automatic cross-conversion makes all the versions equivalently first-class citizens, which is good enough for us. The XSLT convertors start with XML and convert to the other formats. In practice, ElasticHosts will likely start with TXT, and convert from there to the JSON, XML, etc - it would be great to see automatic convertors in this opposite direction too, to validate that it can be done. Writing these will also impose discipline and prevent creation of unnecessarily complex datastructures, which is always a risk in XML.
You can see the basics in action thanks to my Google App Engine reference implementation at http://occitest.appspot.com/ (as well as HTML, JSON and TXT versions of same)
http://occitest.appspot.com/ http://www.w3.org/2005/08/online_xslt/xslt?xslfile=http%3A%2F%2Focci.googlecode.com%2Fsvn%2Ftrunk%2Fxml%2Focci-to-html.xsl&xmlfile=http%3A%2F%2Foccitest.appspot.com http://www.w3.org/2005/08/online_xslt/xslt?xslfile=http%3A%2F%2Focci.googlecode.com%2Fsvn%2Ftrunk%2Fxml%2Focci-to-json.xsl&xmlfile=http%3A%2F%2Foccitest.appspot.com http://www.w3.org/2005/08/online_xslt/xslt?xslfile=http%3A%2F%2Focci.googlecode.com%2Fsvn%2Ftrunk%2Fxml%2Focci-to-text.xsl&xmlfile=http%3A%2F%2Foccitest.appspot.com
I'm not going to comment on the XML, since Enterprise XML design is not our forte. I will go through the TEXT and JSON versions in some detail. Here's a sample excerpt in XML:
<entry> <id>urn:uuid:47bb7df8-587e-47fa-bd89-6f2f81c14b19</id> <title>Virtual Machine #1</title> <summary>Sample Compute Resource</summary> <updated>2009-05-04T09:52:37Z</updated> <link href="/47bb7df8-587e-47fa-bd89-6f2f81c14b19" /> <link rel="http://purl.org/occi/storage#device" href="urn:uuid:4cc8cf62-69a4-4650-9e8c-7d4c516884df" title="Hard Drive"/> <link rel="http://purl.org/occi/network#interface" href="urn:uuid:dc88b244-145f-49e4-be7c-0880dcad42e9" title="Internet Connection"/> <link rel="http://purl.org/occi/network#interface" href="urn:uuid:253d83dd-e417-4e1f-9958-8c0a63120475" title="Private Network"/> </entry>
in JSON: [I assume the '\n' and '\/' in the strings are mistakes. It'd also be good if the XSLT-converted JSON had nice indentation, like I've produced below]
{ "id":"urn:uuid:47bb7df8-587e-47fa-bd89-6f2f81c14b19", "title":"Virtual\nMachine\n#1", "summary":"Sample\nCompute\nResource", "updated":"2009-05-04T09:52:37Z", "link":[ { "href":"\/47bb7df8-587e-47fa-bd89-6f2f81c14b19" }, { "rel":"http:\/\/purl.org\/occi\/storage#device", "href":"urn:uuid:4cc8cf62-69a4-4650-9e8c-7d4c516884df", "title":"Hard\nDrive" }, { "rel":"http:\/\/purl.org\/occi\/network#interface", "href":"urn:uuid:dc88b244-145f-49e4-be7c-0880dcad42e9", "title":"Internet\nConnection" }, { "rel":"http:\/\/purl.org\/occi\/network#interface", "href":"urn:uuid:253d83dd-e417-4e1f-9958-8c0a63120475", "title":"Private\nNetwork" } ] }
and in TXT:
[47bb7df8-587e-47fa-bd89-6f2f81c14b19] title|Virtual Machine #1 summary|Sample Compute Resource updated|2009-05-04T09:52:37Z link|||/47bb7df8-587e-47fa-bd89-6f2f81c14b19 link|http://purl.org/occi/storage#device|Hard Drive|urn:uuid:4cc8cf62-69a4-4650-9e8c-7d4c516884df link|http://purl.org/occi/network#interface|Internet Connection|urn:uuid:dc88b244-145f-49e4-be7c-0880dcad42e9 link|http://purl.org/occi/network#interface|Private Network|urn:uuid:253d83dd-e417-4e1f-9958-8c0a63120475 etag|
Going through the text version...
[47bb7df8-587e-47fa-bd89-6f2f81c14b19]
To simplify parsing even further, I'd write this as: id|47bb7df8-587e-47fa-bd89-6f2f81c14b19 and have the blank line also as the separator between objects
title|Virtual Machine #1 summary|Sample Compute Resource updated|2009-05-04T09:52:37Z
These look good - simple key-value pairs. Presumably we'll also add some actual parameters of the virtual machine, e.g. smp|2 cpu|2000 mem|1024 It would be good to work these into the examples, TXT, JSON and XML.
link|||/47bb7df8-587e-47fa-bd89-6f2f81c14b19
It's good that we have an end-point for editing the object directly. I'd make this a simple key-value rather than having blank fields: link|/47bb7df8-587e-47fa-bd89-6f2f81c14b19
link|http://purl.org/occi/storage#device|Hard Drive|urn:uuid:4cc8cf62-69a4-4650-9e8c-7d4c516884df link|http://purl.org/occi/network#interface|Internet Connection|urn:uuid:dc88b244-145f-49e4-be7c-0880dcad42e9 link|http://purl.org/occi/network#interface|Private Network|urn:uuid:253d83dd-e417-4e1f-9958-8c0a63120475
There are four fields here: 'link', a schema, a name and an object's UUID. However there's an important one missing - the specification of _how_ the other object is bound to the virtual machine (e.g. is the drive bound as IDE or SCSI, and to which bus? Which network is which virtual NIC?). This extra field will be needed in the XML too, e.g. as 'type': <link type="ide:0:0" rel="http://purl.org/occi/storage#device" href="urn:uuid:4cc8cf62-69a4-4650-9e8c-7d4c516884df" title="Hard Drive"/> One this is specified, the first three fields aren't actually necessary in the TXT version, which can just be: ide:0:0|4cc8cf62-69a4-4650-9e8c-7d4c516884df nic:0|dc88b244-145f-49e4-be7c-0880dcad42e9 nic:1|253d83dd-e417-4e1f-9958-8c0a63120475 There's no need to specify the schema, since this is uniquely determined by the link type (and in any case only relevant to the XML), no need to specify 'link', since it always is for this key, and no need to specify the name, since that's the name of the object with the given UUID.
etag|
What's this doing? Can it be deleted? Putting these together, the original:
[47bb7df8-587e-47fa-bd89-6f2f81c14b19] title|Virtual Machine #1 summary|Sample Compute Resource updated|2009-05-04T09:52:37Z link|||/47bb7df8-587e-47fa-bd89-6f2f81c14b19 link|http://purl.org/occi/storage#device|Hard Drive|urn:uuid:4cc8cf62-69a4-4650-9e8c-7d4c516884df link|http://purl.org/occi/network#interface|Internet Connection|urn:uuid:dc88b244-145f-49e4-be7c-0880dcad42e9 link|http://purl.org/occi/network#interface|Private Network|urn:uuid:253d83dd-e417-4e1f-9958-8c0a63120475 etag|
Turns into: id|47bb7df8-587e-47fa-bd89-6f2f81c14b19 title|Virtual Machine #1 summary|Sample Compute Resource updated|2009-05-04T09:52:37Z smp|2 cpu|2000 mem|1024 link|/47bb7df8-587e-47fa-bd89-6f2f81c14b19 ide:0:0|4cc8cf62-69a4-4650-9e8c-7d4c516884df nic:0|dc88b244-145f-49e4-be7c-0880dcad42e9 nic:1|253d83dd-e417-4e1f-9958-8c0a63120475 Which is shorter, simpler and describes the virtual server more fully (3 extra properties + the link attachment points). We can also render this same thing in JSON: { "id": "47bb7df8-587e-47fa-bd89-6f2f81c14b19", "title": "Virtual Machine #1", "summary": "Sample Compute Resource", "updated": "2009-05-04T09:52:37Z", "smp": 2, "cpu": 2000, "mem": 1024, "link": "/47bb7df8-587e-47fa-bd89-6f2f81c14b19", "ide:0:0": "4cc8cf62-69a4-4650-9e8c-7d4c516884df", "nic:0": "dc88b244-145f-49e4-be7c-0880dcad42e9", "nic:1": "253d83dd-e417-4e1f-9958-8c0a63120475" } Which again is shorter, simpler and more descriptive than the original. Sam: please can you take these changes on board: - update the XML example with the 3 extra properties, the link attachment points and probably some actuators too (like start and stop) - update the XSLT conversions to produce the improved TXT and JSON formats Thanks! Richard.