[occi-wg] OCCI Walkthrough

[Richard Davies]

Sam, Andy et al,

Chris and I have been reviewing the latest API design document,
walkthrough, and process.

We see an enormous step forward, and are very excited by this. With the
latest design, OCCI looks like it'll be an API which ElasticHosts will be
enthusiastic to implement. Thank you to Sam and the committee for working
through some challenging times and also for taking on board much of our
feedback.


I've made some updates to the Features Matrix, Use Cases and API Review on
the website. I'm writing out my feedback on format issues in the design and
walkthrough below. I'll update the Wiki along these lines once people agree.

Cheers,

Richard.


Descriptor formats
------------------

I see 3 descriptor formats (text/plain, application/json and
application/xml) and 1 extra descriptor-like format for creation
(application/x-www-form-urlencoded).

All of these make sense and are based around the same flat key-value pairs,
which look reasonable.

I have a few points of consistency:

- Various mime types are discussed, e.g. text/plain on the API Design, but
  application/occi+text on the Walkthrough. Needs to be consistent

- Qualification of attributes varies. e.g. 'cores' on the API Design, but
  'compute.cores' on the Walkthrough. Again needs to be consistent. We'd
  favour plain 'cores', but are not too bothered.

- Which of the descriptor formats are compulsory and hence required for
  interoperability?

  The API Design states that the first 3 are all compulsory.

  The walkthrough then adds an application/x-www-form-encoded format
  specifically for initial create POST and for Requests. Would
  application/occi+xml be acceptable in the create POST?  Would
  application/x-www-form-urlencoded be acceptable for a PUT? Are we really
  saying that there are 4 compulsory descriptor formats throughout?

- For the Retrieve operation on the Walkthrough, we should support the HTTP
  Accept: header to select a output descriptor format.


Collection formats
------------------

I very much like the way that there is now a clear separation between the
descriptor formats and AtomPub as a collection format (see API Design).

This makes it clear that all of the OCCI work is in the descriptor format
for the payloads, and these can be wrapped in Atom according to the standard
Atom RFCs in the exactly same way that that another payload such as OVF
could equally be wrapped in Atom. This is probably a good way of
transferring potentially mixed sets of OCCI descriptors, OVF, etc., all
wrapped in a single feed, with updated dates, etags, etc.


However, I do wonder if a separate collection format is necessary at all for
basic use.

Each of the descriptor formats itself can very naturally transfer multiple
resources (if we add the id as an attribute to each resource):

text/plain: put a blank line between resources
application/json: put the resources inside a JSON list
application/xml: have multiple <occi>...</occi> stanzas.


I would like to support returning collections in the native descriptor
formats, as above. We should support the HTTP Accept: header when requesting
a collection to determine which of the descriptor formats or Atom is used.