[occi-wg] Syntax of OCCI API

[Richard Davies]

Sam Johnston wrote:
> What I've done so far is based it on an extremely simple, well specified
> and common XML structure (Atom - RFC 4287) and (following Sun's example)
> embedded links for operations:
> 
>   http://example.com/decca5a5-8952-4004-9793-cdbbf05c3c63/ops/start
> 
> These links can obviously be actuated by any HTTP client and they could
> obviously be embedded in a format of your choice (e.g. json).

Hi Sam,

The links for operations look good - a simple HTTP POST to a straight url.


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.

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 '...'.

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.

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.

Cheers,

Richard.