[occi-wg] "Approachability" of API

[Sam Johnston]

On Mon, May 18, 2009 at 1:23 PM, Richard Davies <
richard.davies at elastichosts.com> wrote:

> Richard Davies wrote:
> > My feeling is that a POJ/POX rendering is a smaller amount of JSON/XML
> > [than AtomPub] with less wrapping around it
>
> Sam Johnston wrote in a separate thread:
> > IOW, your average [AtomPub] request to ElasticHosts is going to be
> > skeletal while your average request to VMware (if they ever implement it)
> > will be relatively fat. Who cares?
>
> This is something which I love to understand better - how skeletal the
> minimum AtomPub request can be. This would help me to understand how much
> "weight" which we are taking on comparing AtomPub vs. POX/POJ.
>
> Sam - can you help me work this out - I've started below...
>

Ok, very happy to see this progress to specific technical questions...


> <snip>
> What is the set of changes I need to make to get from this POX to the
> minimum AtomPub? Assume for this thought experiment that I don't want to
> benefit from any additional services which AtomPub provides, but just want
> the same experience as with the POX rendering.
>

   - Your object element becomes an entry
   - If you have multiple entries you wrap them in a feed
   - Atom categories are very flexible - you can have multiple namespaces
   for a start (e.g. resource types vs operating systems vs user tags) - but
   otherwise they're pretty close
   - Attributes go into namespaces - I see this as a feature, not a bug, as
   it makes what you're talking about clear. For example, compute:cores,
   memory:size, memory:speed
   - Links are generic (who says it's IDE anyway... what about [i]SCSI?)

As you can see most of the changes are superficial.

I can name a few:
>
> - There's a <feed> tag which wraps all of the entries/objects. It has
>  various other subtags of its own (e.g. title, subtitle, author). Am I
>  right that all of these are static and could be bolted on by a server or
>  ignored by a client which skips straight to the entries?
>

Yup, and the wrapping feed is optional.


> - Am I right that this <feed> tag is only relevant when getting the entire
>  overall feed? When inserting or updating individual entries we still send
>  the entry alone.
>

Yup.


> - There are 'updated' tags on every entry. Can these be ignored by clients
>  and set to the current time by servers?
>

Yes, but while it's ok to ignore them client side if you don't need them,
giving accurate information on the server side will allow clients to make
optimisations. That is, it will work if you don't, but nothing will ever be
cached.


> - All UUIDs are prefixed by urn:uuid:
>

Yup, they have to be URIs per Atom. That's OK by me - I think there's lots
of advantages in enforcing use of UUIDs but there's alternatives like the
tag: namespace and who knows what other resources will need to be modeled in
future?


> - Each entry has a link confirming its own end point (versus the POX
>  rendering just defines fixed end points for objects).
>

Entries don't have to be ephemeral - that is, you might be retrieving it
from a queue, file, cache etc. and it's useful to know where you can find
the latest version.


> - Each entry will have links confirming all of its actuators (versus the
> POX
>  rendering just defines a fixed URL scheme for the actuators).
>

All the URLs we're going to use should be advertised via the protocol -
configuring only a single entry point makes a lot of sense. It's also
necessary for HATEOAS - that is, advertising what states and transitions are
reachable. Templates might be cloneable but not startable for example, and
we don't know what the future holds in terms of new states/transitions.


> - The syntax for linking one noun to another is different, and additionally
>  specifies a schema for the link (defined as fixed in the direct
> rendering).
>

Yup, links can be used to link whatever you like to whatever you like. If
your network needs to point at an NMS in the form of a compute resource then
fine.


> - I believe that the nouns' attributes will end up inside a <content> tag
>  inside the entry, rather than being at the top level.
>

This is something of a religious debate and something that Atom purists
would probably agree with you on. That said, there's nothing stopping us
from putting this stuff at the root and leaving the content element for e.g.
an [X]HTML rendering. In fact you can replace the content element with a
link element if you want.


> - A HTTP DELETE call has to specify an ETag version as part of a delete
> call
>

No, but it's safer to do so (e.g. so you don't delete a resource that has
changed since you retrieved it). It's fine if you don't, but implementations
could in theory reject your request.


> Is that list correct? What else is there?


Let me know as you come up with more questions - I have to go get ready for
an early flight to the Cloud Computing Expo in London (see some of you
there).

Sam
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.ogf.org/pipermail/occi-wg/attachments/20090519/f06d3964/attachment.html